man: commands and single-quotes vs. asterisks

[Michael(tm) Smith-4]

I notice that the asciidoc man page[1] has the command name
"asciidoc" marked up with single quotes instead of asterisks.

  SYNOPSIS
  --------
  'asciidoc' [OPTIONS] FILE

And I notice that the git and mercurial man pages seem to have
followed that example and used single-quotes around command names
in the source for their docs.

The problem with that is that since it causes the command names to
be displayed in italic in output, that output is at odds with the
conventions for how command names are marked up in existing man pages.

Existing man pages pretty much universally have command names
displayed in bold. And guides like the man-pages(7) file[2] say
"Any reference to the subject of the current manual page should be
written with the name in bold."

So I'd like to suggest the asciidoc maintainers consider updating
the asciidoc man-page/example file so that the "asciidoc" command
name is marked up with asterisks instead of single quotes.

  --Mike

[1] http://www.methods.co.nz/asciidoc/asciidoc.1.txt
[2] http://kerneltrap.org/man/linux/man7/man-pages.7


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

[Stuart Rackham]

Michael(tm) Smith wrote:

> I notice that the asciidoc man page[1] has the command name
> "asciidoc" marked up with single quotes instead of asterisks.
>
>   SYNOPSIS
>   --------
>   'asciidoc' [OPTIONS] FILE
>
> And I notice that the git and mercurial man pages seem to have
> followed that example and used single-quotes around command names
> in the source for their docs.
>
> The problem with that is that since it causes the command names to
> be displayed in italic in output, that output is at odds with the
> conventions for how command names are marked up in existing man pages.
>
> Existing man pages pretty much universally have command names
> displayed in bold. And guides like the man-pages(7) file[2] say
> "Any reference to the subject of the current manual page should be
> written with the name in bold."
>
> So I'd like to suggest the asciidoc maintainers consider updating
> the asciidoc man-page/example file so that the "asciidoc" command
> name is marked up with asterisks instead of single quotes.

You are absolutely correct. The reasoning behind the current situation
goes way back to an ill informed off-hand decision I made when I first
wrote the AsciiDoc man page: I just didn't like the look of *asciidoc*
compared to 'asciidoc'. I've rewritten the AsciiDoc man page to
(hopefully) conform to the man man-pages recommendations including
putting options in bold and option arguments in italics. Let me know if
there are any omissions/mistakes in the changeset:
http://hg.sharesource.org/asciidoc/rev/b8d4acbe57c9


>
>   --Mike
>
> [1] http://www.methods.co.nz/asciidoc/asciidoc.1.txt
> [2] http://kerneltrap.org/man/linux/man7/man-pages.7
>
>

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

[Michael(tm) Smith-4]

Stuart Rackham <srackham@...>, 2008-04-03 12:06 +1300:

> You are absolutely correct. The reasoning behind the current situation
> goes way back to an ill informed off-hand decision I made when I first
> wrote the AsciiDoc man page: I just didn't like the look of *asciidoc*
> compared to 'asciidoc'. I've rewritten the AsciiDoc man page to
> (hopefully) conform to the man man-pages recommendations including
> putting options in bold and option arguments in italics. Let me know if
> there are any omissions/mistakes in the changeset:
> http://hg.sharesource.org/asciidoc/rev/b8d4acbe57c9

That all looks correct to me.

But I guess I need to practice what I preach. Your mention of
putting options in bold made me realize there's a big oversight in
the current DocBook XSL manpages stylesheet.

This isn't something that will affect Asciidoc users (since
Asciidoc doesn't generate DocBook <arg> etc. markup for command
synopsis), I realize now that the DocBook XSL manpages stylesheet
doesn't do that (that is, while it does boldface <command>
contents, it doesn't boldface DocBook <arg> contents). It's
clearly wrong that is doesn't. I can't believe I didn't notice it
before now (or that nobody else has). Anyway, I'll change it for
the next (1.74.0) release.

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