Hi Ben,
2009/9/18 Ben Finney <b...@benfinney.id.au>:
> package docutils-writer-manpage
> severity 547254 wishlist
> tags 547254 + wontfix
> thanks
>
> On 18-Sep-2009, Ulrik Sverdrup wrote:
>> Internal man page headings are always all-captialized as we know,
>> for exmaple SYNOPSIS, DESCRIPTION etc.
>
> This isn't always the case. Using this command::
>
> (cd /usr/share/man/ && find . -path './man?/*' | xargs zgrep
> '^\.SH.*[[:lower:]]')
>
> I can see examples of man pages with top-level section headings that
> legitimately include lowercase. Some are:
>
> * debconf(7) from the ‘debconf-doc’ package
> * postconf(5) from the ‘postfix’ package
> * most man pages from the ‘perl-doc’ package
>
> You can see many others in the above-generated list.
>
>> Could rst2man automatically uppercase all the headings? It would be
>> better if you could type up the source document in normal
>> title-cased headings, which is also much better for other formats
>> (web) than all-uppercase.
>
> I disagree. There are a great many other restrictions and conventions
> that apply only to man pages (the main set I know of is detailed in
> ‘man-pages(7)’, but there are probably other divergent conventions)
> and it would be folly for the tool to attempt to enforce them all.
>
> These restrictions don't make sense for a more-general source
> document. Anyone who wants to conform to them completely needs to be
> writing (or somehow generating) a manpage-specific source document
> anyway.
>
> Further, as we see above, to do as you describe would unduly restrict
> the man pages people could produce.
>
> The writer does conform to the conventions where there is no
> reasonable way for the author to produce the desired effect (e.g. the
> upper-cased page name in the ‘TH’ command as distinct from the name in
> the rest of the document). But in cases where conventions differ and
> can be easily followed by the author (as in this case), I don't think
> the formatting tools should impose policy.
Thank you for providing very sensible rationale, I understand.
I want to present my man page on the website, and if anyone ever looks
by in this bug again, CSS can rescue this with some trickery
(titlecase is not an option):
h1 {
text-transform: lowercase;
}
h1:first-letter {
text-transform: capitalize;
}
Ulrik Sverdrup
>
>> So feature request in short:
>>
>> manpage.1.rst::
>>
>> Synopsis
>> --------
>>
>> Turns into::
>>
>> SYNOPSIS
>
> I think this is best done by creating a separate, optional processor
> to turn a generic source document into one that follows the manpage
> conventions you want to follow, which can then be fed into an
> impartial manpage renderer.
>
> Accordingly, I am marking this bug report ‘wontfix’.
>
> Thank you for raising this issue.
>
> --
> \ “Contentment is a pearl of great price, and whosoever procures |
> `\ it at the expense of ten thousand desires makes a wise and |
> _o__) happy purchase.” —J. Balguy |
> Ben Finney <b...@benfinney.id.au>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEAREIAAYFAkqzCqEACgkQIiYF7H0aG3lYqQCg1s2cAPO8qZS4/tIzp5ukvU/N
> VHAAniBhoT6LTVFn5oq/Up5iNJo4jmMy
> =Iqdi
> -----END PGP SIGNATURE-----
>
>
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
