manpage out of date

[rillian]

In the 1.0.0 release (and master) the rustc and rustdoc man pages say they document version '0.13.0 March 2014'.

Looks like some of the contents are stable as well, e.g. the rust manpage suggests '-C target-cpu=help' for which rustc --help gives 'llc -mcpu=help'.

[emberian]

@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]

I prepared pull requests. We should probably figure out a way to update or generate these as part of the build though.

[brson]

Yeah, it least using a template to plugin the version number automatically would help.

[steveklabnik]

Changing to A-build as the immediate documenation situation has been addressed.

[sanmai-NL]

Current master has a man page title as if it's still Rust 1.2.0.

rust/man/rustc.1

Line 1 in a76698b

.TH RUSTC "1" "August 2015" "rustc 1.2.0" "User Commands"

@steveklabnik, is there perhaps work underway, planned or desired to autoproduce the man pages?

[brson]

@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]

IIRC, there was some work in Cargo to do generated manpages.

[sanmai-NL]

@brson, see my PR #34254.

Reasons to keep the man pages:

1. The man pages are there, removing them is a bit of lost work then. If they're not desired because of Windows, then creating them should've been given more thought at the outset.
2. I think they are expected by users on Unix for utilities with so many command line options, such as rustc. Having them can be considered necessary for feature parity with gcc, 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]

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 [email protected], wrote:

@brson(https://github.com/brson), see my PR#34254(#34254).

Reasons to keep the man pages:

1. The man pages are there, removing them is a bit of lost work then. If they're not desired because of Windows, then creating them should've been given more thought at the outset.
2. I think they are expected by users on Unix for utilities with so many command line options, such asrustc. 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 seenDocker Engine's man page production workflow(https://github.com/docker/docker/blob/9a8affb0ffdf6010fca6a1c8fb00c9e0a38845d6/man/README.md)? I personally would prefer that you'd start usingAsciidoctor(http://asciidoctor.org/docs/user-manual/#man-pages), since that 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.

—
You are receiving this because you were mentioned.
Reply to this email directly,view it on GitHub(#25689 (comment)), ormute the thread(https://github.com/notifications/unsubscribe/AABsis_n8P2KaCfeaJbJ_rGiy_a6v66bks5qLRSUgaJpZM4Ej8Rp).