-
Notifications
You must be signed in to change notification settings - Fork 13.6k
Closed
Labels
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-bugCategory: This is a bug.Category: This is a bug.P-lowLow priorityLow priorityT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.
Metadata
Metadata
Assignees
Labels
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-bugCategory: This is a bug.Category: This is a bug.P-lowLow priorityLow priorityT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.
Type
Projects
Milestone
Relationships
Development
Select code repository
Activity
emberian commentedon May 22, 2015
@rillian would you like to send a PR updating the man page (they're in https://github.com/rust-lang/rust/tree/master/man), or should someone else?
rillian commentedon May 26, 2015
I prepared pull requests. We should probably figure out a way to update or generate these as part of the build though.
brson commentedon May 27, 2015
Yeah, it least using a template to plugin the version number automatically would help.
Rollup merge of rust-lang#25807 - rillian:manpages, r=alexcrichton
Rollup merge of rust-lang#25807 - rillian:manpages, r=alexcrichton
Rollup merge of rust-lang#25807 - rillian:manpages, r=alexcrichton
steveklabnik commentedon Jun 9, 2015
Changing to A-build as the immediate documenation situation has been addressed.
sanmai-NL commentedon Jun 12, 2016
Current
master
has a man page title as if it's still Rust 1.2.0.rust/man/rustc.1
Line 1 in a76698b
@steveklabnik, is there perhaps work underway, planned or desired to autoproduce the man pages?
brson commentedon Jun 12, 2016
@sanmai-NL, there's no such effort underway.
As a first step, I'd be interested in a patch that just fills in the version automatically.
In the long-term I'm not sure if producing the full man pages is desirable or not, but relates to the problem of man pages being useless on windows.
A reason the man pages aren't updated much may be that they are rarely seen. If this information was written as part of the published documentation, so more people could use it, then converted to man pages it may get more contributions.
steveklabnik commentedon Jun 13, 2016
IIRC, there was some work in Cargo to do generated manpages.
sanmai-NL commentedon Jun 13, 2016
@brson, see my PR #34254.
Reasons to keep the man pages:
rustc
. Having them can be considered necessary for feature parity withgcc
,ocamlc
, basically any popular compiler.I agree that writing man pages manually is undesirable. Have you seen Docker Engine's man page production workflow? I personally would prefer that you'd start using Asciidoctor, since that's basically the best OSS technical documentation system around, and it can render man pages as well as DocBook, responsive (X)HTML5, PDF, etc.
What about thinking differently, not along the lines of superseding the man pages with ‘the published documentation’ but rather considering them part of ‘the documentation’ and accounted for as such.
steveklabnik commentedon Jun 13, 2016
The recent man page work on cargo first used ASCIIDOC, but we rejected it in favor of keeping the consistency of Markdown everywhere.
On Jun 13, 2016, 10:28 +0200, Sander Maijersnotifications@github.com, wrote:
template month/year, version into man pages while building dist tarball
Auto merge of #46514 - zackmdavis:sticking_it_to_the_man, r=alexcrichton