man-page "manual", "source", and "version" data

[Michael(tm) Smith-4]

I'd like to suggest that asciidoc provide built-in processing
support for some additional document-header attributes of general
use for specifying particular metadata in man-page output:

  :ManSource:    Git
  :ManVersion:   {git_version}
  :ManManual:    Git Manual

Background on that suggestion is this: I notice that the git doc
build has an asciidoc.conf file that in part contains the following:

  ifdef::doctype-manpage[]
  ifdef::backend-docbook[]
  [header]
  template::[header-declarations]
  <refentry>
  <refmeta>
  <refentrytitle>{mantitle}</refentrytitle>
  <manvolnum>{manvolnum}</manvolnum>
  <refmiscinfo class="source">Git</refmiscinfo>
  <refmiscinfo class="version">{git_version}</refmiscinfo>
  <refmiscinfo class="manual">Git Manual</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>{manname}</refname>
    <refpurpose>{manpurpose}</refpurpose>
  </refnamediv>
  endif::backend-docbook[]
  endif::doctype-manpage[]

That follows the DocBook form for marking up "miscellaneous
information" for refentry instances, and (along with other data in
the asciidoc source) when processed with the DocBook XSL manpages
stylesheet, causes the following groff fragment to be output in,
e.g., the git-merge.1 page:

  .TH "GIT\-MERGE" "1" "03/28/2008" "Git 1.5.4.3.450.gb92" "Git Manual"

So the "source+version" data is combined and put into the
2nd-to-last field, and the "manual" data is put into the last
field. When viewed on most Linux systems, the header and footer of
that page look like this:

  GIT-MERGE(1)               Git Manual             GIT-MERGE(1)
  ...
  Git 1.5.4.3.450.gb92       03/28/2008             GIT-MERGE(1)

So, without having a way to specify the "manual" data and "source"
and/or "version" data, the parts of the header and footer that have
"Git Manual" and  "Git 1.5.4.3.450.gb92" would just be blank.

So what I'm suggesting is that asciidoc provide some means to mark
up that information in the asciidoc document header and to
generate to corresponding DocBook markup from that (so that users
don't necessarily need to know anything about DocBook, nor need to
use a custom config file with DocBook markup to be able to add it).

The "ManSource", "ManVersion", and ManManual names are just
suggestions. I don't think it matters much what they are named as
long as the User Guide explains what they are and where their
contents will end up in the final man-page output.

  --Mike

--
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Michael(tm) Smith-4]

"Michael(tm) Smith" <mike@...>, 2008-03-28 13:46 +0900:

> I'd like to suggest that asciidoc provide built-in processing
> support for some additional document-header attributes of general
> use for specifying particular metadata in man-page output:
>
>   :ManSource:    Git
>   :ManVersion:   {git_version}
>   :ManManual:    Git Manual
[...]

For additional information about what kind of data should actually
go into those fields, here's how DocBook defines them:

  source
    The name of the software product or component to which this
    topic applies
  version
    The version of the software product or component to which this
    topic applies
  manual
    The section title of the reference page (e.g., User Commands)

  http://www.docbook.org/tdg5/en/html/refmiscinfo.html#attribute-descriptions

And here is what the current GNU/Linux man-pages(7) file has:

  source
    The source of the command, function, or system call. For those
    few man-pages pages in Sections 1 and 8, probably you just
    want to write GNU. For system calls, just write "Linux"... (An
    earlier practice was to write the version number of the kernel
    from which the manual page was being written/checked. However,
    this was never done consistently, and so was probably worse
    than including no version number. Henceforth, avoid including
    a version number.)...

  manual
    The title of the manual (e.g., for Section 2 and 3 pages in the
    man-pages package, use "Linux Programmer's Manual").

  http://kerneltrap.org/man/linux/man7/man-pages.7

Note that as far the "avoid including a version number" admonition
in the man-pages(7) file, that's not intended as a general
admonition against putting version information in that field. The
man-pages(7) intro says:

   This page describes the conventions that should be employed
   when writing man pages for the Linux man-pages project, which
   comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
   The conventions described on this page may also be useful for
   authors writing man pages for other projects.

So, its guidelines are primarily intended for people writing docs
for the Linux man-pages project, and the admonition against
putting version info is for the specific case of writing "core
Linux" docs for that project, not for man pages in general.

In the case of applications such as Git, it is often very useful
to end users to know what version of the app or library the
corresponding man page was written for.

  --Mike
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Stuart Rackham]

Thanks for the nicely detailed suggestion Mike.
I've added {mansource}, {manversion} and {manmanual} attributes (see
changeset http://hg.sharesource.org/asciidoc/rev/134daaaebc9b).
Hopefully that will do the trick.

Cheers, Stuart


Michael(tm) Smith wrote:

> "Michael(tm) Smith" <mike@...>, 2008-03-28 13:46 +0900:
>
>> I'd like to suggest that asciidoc provide built-in processing
>> support for some additional document-header attributes of general
>> use for specifying particular metadata in man-page output:
>>
>>   :ManSource:    Git
>>   :ManVersion:   {git_version}
>>   :ManManual:    Git Manual
> [...]
>
> For additional information about what kind of data should actually
> go into those fields, here's how DocBook defines them:
>
>   source
>     The name of the software product or component to which this
>     topic applies
>   version
>     The version of the software product or component to which this
>     topic applies
>   manual
>     The section title of the reference page (e.g., User Commands)
>
>   http://www.docbook.org/tdg5/en/html/refmiscinfo.html#attribute-descriptions
>
> And here is what the current GNU/Linux man-pages(7) file has:
>
>   source
>     The source of the command, function, or system call. For those
>     few man-pages pages in Sections 1 and 8, probably you just
>     want to write GNU. For system calls, just write "Linux"... (An
>     earlier practice was to write the version number of the kernel
>     from which the manual page was being written/checked. However,
>     this was never done consistently, and so was probably worse
>     than including no version number. Henceforth, avoid including
>     a version number.)...
>
>   manual
>     The title of the manual (e.g., for Section 2 and 3 pages in the
>     man-pages package, use "Linux Programmer's Manual").
>
>   http://kerneltrap.org/man/linux/man7/man-pages.7
>
> Note that as far the "avoid including a version number" admonition
> in the man-pages(7) file, that's not intended as a general
> admonition against putting version information in that field. The
> man-pages(7) intro says:
>
>    This page describes the conventions that should be employed
>    when writing man pages for the Linux man-pages project, which
>    comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
>    The conventions described on this page may also be useful for
>    authors writing man pages for other projects.
>
> So, its guidelines are primarily intended for people writing docs
> for the Linux man-pages project, and the admonition against
> putting version info is for the specific case of writing "core
> Linux" docs for that project, not for man pages in general.
>
> In the case of applications such as Git, it is often very useful
> to end users to know what version of the app or library the
> corresponding man page was written for.
>
>   --Mike
> _______________________________________________
> asciidoc-discuss mailing list
> asciidoc-discuss@...
> http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss
>

_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss

[Michael(tm) Smith-4]

Hi Stuart,

> @2008-04-02 12:57 +1300:
> Thanks for the nicely detailed suggestion Mike.
> I've added {mansource}, {manversion} and {manmanual} attributes (see
> changeset http://hg.sharesource.org/asciidoc/rev/134daaaebc9b).
> Hopefully that will do the trick.

I just took a look and it seems like that will indeed do the
trick. Thanks much for adding the support. In the case of the git
docs, it's one less customization/patch they'll need to maintain,
and for new users, I think it'll make it much easier for them to
the man-page output they'd expect.

Cheers,

  --Mike

> Michael(tm) Smith wrote:
> > "Michael(tm) Smith" <mike@...>, 2008-03-28 13:46 +0900:
> >
> >> I'd like to suggest that asciidoc provide built-in processing
> >> support for some additional document-header attributes of general
> >> use for specifying particular metadata in man-page output:
> >>
> >>   :ManSource:    Git
> >>   :ManVersion:   {git_version}
> >>   :ManManual:    Git Manual
> > [...]
> >
> > For additional information about what kind of data should actually
> > go into those fields, here's how DocBook defines them:
> >
> >   source
> >     The name of the software product or component to which this
> >     topic applies
> >   version
> >     The version of the software product or component to which this
> >     topic applies
> >   manual
> >     The section title of the reference page (e.g., User Commands)
> >
> >   http://www.docbook.org/tdg5/en/html/refmiscinfo.html#attribute-descriptions
> >
> > And here is what the current GNU/Linux man-pages(7) file has:
> >
> >   source
> >     The source of the command, function, or system call. For those
> >     few man-pages pages in Sections 1 and 8, probably you just
> >     want to write GNU. For system calls, just write "Linux"... (An
> >     earlier practice was to write the version number of the kernel
> >     from which the manual page was being written/checked. However,
> >     this was never done consistently, and so was probably worse
> >     than including no version number. Henceforth, avoid including
> >     a version number.)...
> >
> >   manual
> >     The title of the manual (e.g., for Section 2 and 3 pages in the
> >     man-pages package, use "Linux Programmer's Manual").
> >
> >   http://kerneltrap.org/man/linux/man7/man-pages.7
> >
> > Note that as far the "avoid including a version number" admonition
> > in the man-pages(7) file, that's not intended as a general
> > admonition against putting version information in that field. The
> > man-pages(7) intro says:
> >
> >    This page describes the conventions that should be employed
> >    when writing man pages for the Linux man-pages project, which
> >    comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
> >    The conventions described on this page may also be useful for
> >    authors writing man pages for other projects.
> >
> > So, its guidelines are primarily intended for people writing docs
> > for the Linux man-pages project, and the admonition against
> > putting version info is for the specific case of writing "core
> > Linux" docs for that project, not for man pages in general.
> >
> > In the case of applications such as Git, it is often very useful
> > to end users to know what version of the app or library the
> > corresponding man page was written for.
> >
> >   --Mike

--
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/
_______________________________________________
asciidoc-discuss mailing list
asciidoc-discuss@...
http://lists.metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss