Re: Bug#1041731: Hyphens in man pages

[Gioele Barabucci]

On 16/10/23 08:36, Gard Spreemann wrote:

I've also found scdoc to be a quite pleasant and very lightweight alternative


I've noticed that the bullet points in man pages produced by scdoc are 
"off" compared to those produced by "pod2man". For example compare


https://manpages.debian.org/unstable/scdoc/scdoc.5.en.html#LISTS

to

https://manpages.debian.org/unstable/debhelper/debhelper.7.en.html#Substitutions_in_debhelper_config_files

The scdoc-produced lists are typeset with small dots, and have no spaces 
between the bullet points and the text. The pod2man lists have instead 
large dots and contain a space between the bullet points and the text.


Perhaps is it just a bug in the man-to-html conversion? Or is scdoc 
producing wrong roff markup?


Regards,

--
Gioele Barabucci

Re: Bug#1041731: Hyphens in man pages

[Colin Watson]

My plan, as indicated in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1041731#62, had been
to leave things much as they are for most of the period while trixie is
in development, and then put the ".char - \-" etc. workarounds back in
place for nroff output for trixie's release; this would have meant a
higher chance of more manual page authoring tools being updated to
handle the groff input language more strictly (although this isn't
always easy, as Russ has indicated, since sometimes the input languages
of those tools are less rich than groff).

However, after wading through an enormous amount of inordinately verbose
stuff in my inbox about this, I'm afraid I've now lost patience with the
whole thing and am definitely not willing to put up with it for another
year or more, so I'm putting the workaround back in place now.  Sorry to
anyone who will end up dissatisfied by non-terminal printed output as a
result.

  https://salsa.debian.org/debian/groff/-/commit/d5394c68d7

It is still true that being strict about the use of the "\-", "\[aq]",
"\[ga]", "\[ha]", and "\[ti]" escape sequences (as opposed to "-", "'",
"`", "^", and "~" respectively) will produce better printed output.

-- 
Colin Watson (he/him)  [cjwat...@debian.org]

Re: Bug#1041731: Hyphens in man pages

[Gard Spreemann]

On October 16, 2023 2:41:08 AM GMT+02:00, "Trent W. Buck"  
wrote:
>FWIW, there are lighter alternatives than pandoc:
>
>pandoc:After this operation, 174 MB of 
> additional disk space will be used.
>sphinx-doc (sphinx-build -b man):  After this operation, 140 MB of 
> additional disk space will be used.
>rst2man (python3-docutils):After this operation, 37.6 MB of 
> additional disk space will be used.
>pod2man (perl):perl is already the newest version 
> (5.36.0-9).
>
>I'm not going to bother measuring docbook ;-)

I've also found scdoc to be a quite pleasant and very lightweight alternative: 
https://tracker.debian.org/pkg/scdoc

--  Gard

Re: Bug#1041731: Hyphens in man pages

[G. Branden Robinson]

At 2023-10-15T13:11:47-0700, Russ Allbery wrote:
> Sorry for my original message, which was very poorly worded and
> probably incredibly confusing.  Let me try to make less of a hash of
> it.  I think what I'm proposing is something like:

My reply to this didn't make it to the -devel list even after several
hours; I suppose it was blocked due to my inclusion of a PDF attachment.

Those who are curious about the issue can read it at
.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Bug#1041731: Hyphens in man pages

[Trent W. Buck]

On Sun 15 Oct 2023 17:33:07 +0200, Iustin Pop wrote:
> At least you're not lazy. I am, so what I did many times is add a
> build-depends on pandoc, and write the man page in rst or md. I think
> that's a worse solution (pandoc is really heavy), but at least, I don't
> have to go back to *roff.

FWIW, there are lighter alternatives than pandoc:

pandoc:After this operation, 174 MB of 
additional disk space will be used.
sphinx-doc (sphinx-build -b man):  After this operation, 140 MB of 
additional disk space will be used.
rst2man (python3-docutils):After this operation, 37.6 MB of 
additional disk space will be used.
pod2man (perl):perl is already the newest version 
(5.36.0-9).

I'm not going to bother measuring docbook ;-)

If you are writing manpages by hand, this is an excellent overview:

https://manpages.debian.org/bookworm/manpages/man.7.en.html

See also:

https://www.oreilly.com/library/view/mastering-perl/9780596527242/ch15.html 
(POD)
https://www.docutils.org/docs/user/manpage.html#todo-open-issues


signature.asc
Description: PGP signature

Re: Bug#1041731: Hyphens in man pages

[Russ Allbery]

"G. Branden Robinson"  writes:

> How about this?

>  \- Minus sign.  \- produces the basic Latin hyphen‐minus
> specifying Unix command‐line options and frequently used in
> file names.  “-” is a hyphen in roff; some output devices
> replace it with U+2010 (hyphen) or similar.

Sorry for my original message, which was very poorly worded and probably
incredibly confusing.  Let me try to make less of a hash of it.  I think
what I'm proposing is something like:

\-   Basic Latin hyphen­minus (U+002D) or ASCII hyphen.  This is the
 character used for Unix command­line options and frequently in file
 names.  It is non-breaking; roff will not wrap lines at this
 character.  "-" (without the "\") is a true hyphen in roff, which is
 a different character; some output devices replace it with U+2010
 (hyphen) or similar.

What I was trying to get at but didn't express very well was to include
the specific Unicode code point and to avoid the term "minus sign" because
this character is not a minus sign in typography at all (although it is
used that way in code).  A minus sign is U+2212 and looks substantially
different because it is designed to match the appearance of the plus sign.
(For example, the line is often at a different height.)  I don't know if
*roff has a way of producing that character apart from providing it as
Unicode.

The above also explicitly says that it's non-breaking (I believe that's
the case, although please tell me if I got that wrong) and is more
(perhaps excessively) explicit about distinguishing it from "-" because of
all the confusion about this.

-- 
Russ Allbery (r...@debian.org)  

Re: Bug#1041731: Hyphens in man pages

[G. Branden Robinson]

Hi Russ,

At 2023-10-15T12:06:14-0700, Russ Allbery wrote:
> Minor point, but since you posted it

No worries!

> "G. Branden Robinson"  writes:
> 
> > ...
> 
> >  \- Minus sign or basic Latin hyphen‐minus.  \- produces the
> > Unix command‐line option dash in the output.  “-” is a
> > hyphen in the roff language; some output devices replace it
> > with U+2010 (hyphen) or similar.
> 
> The official name of "the Unix command-line option dash" is the
> hyphen-minus character (U+002D).  Given how much confusion there is
> about this, and particularly given how ambiguous the word "dash" is in
> typography (the hyphen-minus is one of 25 dashes in Unicode), you may
> want to say that explicitly in addition to saying that it's the
> character used in UNIX command-line options (and, arguably as
> importantly, in UNIX command names).

How about this?

 \- Minus sign.  \- produces the basic Latin hyphen‐minus
specifying Unix command‐line options and frequently used in
file names.  “-” is a hyphen in roff; some output devices
replace it with U+2010 (hyphen) or similar.

Regards,
Branden


signature.asc
Description: PGP signature