Skip to content

manpage out of date #25689

@rillian

Description

@rillian
Contributor

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'.

Activity

emberian

emberian commented on May 22, 2015

@emberian
Member

@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

rillian commented on May 26, 2015

@rillian
ContributorAuthor

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

brson

brson commented on May 27, 2015

@brson
Contributor

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

added 3 commits that reference this issue on May 27, 2015
steveklabnik

steveklabnik commented on Jun 9, 2015

@steveklabnik
Member

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

sanmai-NL

sanmai-NL commented on Jun 12, 2016

@sanmai-NL

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

.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

brson commented on Jun 12, 2016

@brson
Contributor

@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

steveklabnik commented on Jun 13, 2016

@steveklabnik
Member

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

sanmai-NL

sanmai-NL commented on Jun 13, 2016

@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

steveklabnik commented on Jun 13, 2016

@steveklabnik
Member

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:

@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).

added
C-bugCategory: This is a bug.
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
on Jul 22, 2017
added a commit that references this issue on Dec 5, 2017
207fc0b
added a commit that references this issue on Dec 5, 2017
cfba0d4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsC-bugCategory: This is a bug.P-lowLow priorityT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Participants

      @steveklabnik@brson@rillian@emberian@sanmai-NL

      Issue actions

        manpage out of date · Issue #25689 · rust-lang/rust