Re: mandoc & perl documentation

[Ingo Schwarze <schwarze@usta.de>]

Hi Pali,

getting back to this matter, i had another, closer look and it seems
to me that two aspects were still open:

Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:
> On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote:
>> Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:
>>> On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
>>>> Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:


FIRST ASPECT:
Does mandoc support all font styles that perlpod(1) can request?

>>> E.g. documentation for cpan modules on metacpan.org is very very
>>> similar to documentation in system manpages, use more font
>>> styles (not only monospaced) and looks much better.

[...]
>> Strictly speaking, "monospaced" is a super-family (for example, the
>> Helvetica family is a proportional family and Courier is a
>> monospaced family).
>>
>> But since mandoc does not bother with families at all,
>> it somewhat incorrectly implements "monospaced" as a font
>> style alongside roman, bold, italic, and bold-italic.
>> 
>> That said, which other font styles does metacpan.org use besides
>> roman, bold, italic, and the pseudo-style "monospaced", and what
>> for?  Having a brief look, i failed to find any.

> I<...> - italic text
> B<...> - bold text
> C<...> - code text in a typewriter font (indication that this
>          represents program text or some other form of computerese)
> F<...> - filenames, displayed in italics

I checked all these, pod2man(1) translates them as follows:

 * I<...>   to   \fI...\fR
 * B<...>   to   \fB...\fR
 * C<...>   to   \f(CW\*(C`...\*(C'\fR   ==   \f(CW"..."\fR
 * F<...>   to   \fI...\fR

Mandoc handles all of \fI \fR \fB \f(CW, so there should be nothing
to fix so far, right?

It appears F<...> behaves exactly like I<...>, so i'll disregard it
below.

> And you can do any combination of them (e.g. typewriter font which is
> both bold and italic together).

So, let's check the combinations:

 * I<B<...>>      to   \fI\f(BI...\fI\fR
 * I<C<...>>      to   \fI\f(CI"..."\fI\fR
 * B<I<...>>      to   \fB\f(BI...\fB\fR
 * B<C<...>>      to   \fB\f(CB"..."\fB\fR
 * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
 * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
 * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
 * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
 * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
 * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
 * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
 * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
 * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR

Mandoc also handles \f(BI \f(CI \f(CB,
so all of that that should work, too.

Of course, in terminal output,

  \f(CW = \fR
  \f(CI = \fI
  \f(CB = \fB

which can't be helped, but apart from that, i don't see anything
that is still unimplemented, or do i overlook something?


SECOND ASPECT:
Does mandoc handle the man(7) code generated from =over/=item
as well as possible?

>>> 3) On that https://man.openbsd.org/strict page is section name "strict
>>> refs" fully invisible. It is joined together with previous paragraph and
>>> also with description of that section. Reader does not see that there is
>>> paragraph about "strict refs" section. It should be visually separated.
>>> To compare, look at metacpan page and search for "strict refs".

>> That is not a section name, not even a subsection name, but merely a
>> list tag formatted as follows:
>> 
>>   =over 6
>> 
>>   =item C<strict refs>
>> 
>> So the vertical spacing that metacpan does *after* the list tag looks
>> dubious for me - doesn't that make many other lists look bad?

> =item directive is used lot of times for describing functions or methods
> of some class.
> 
> In perlpod documentation is written:
> 
> And perhaps most importantly, keep the items consistent: either use
> "=item *" for all of them, to produce bullets; or use "=item 1.",
> "=item 2.", etc., to produce numbered lists; or use "=item foo",
> "=item bar", etc.--namely, things that look nothing like bullets or
> numbers. If you start with bullets or numbers, stick with them, as
> formatters use the first "=item" type to decide how to format the list.
> 
> So it is questionable... Maybe bullets and numbers specified via =item
> should be formatted differently as "=item text"?

Maybe, not sure.  But am i right that if so, that is a task for pod2man(1),
not for mandoc(1)?  Right now, it seems to me that pod2man(1) formats
bulleted and numbered lists as

  .IP "\(bu" 6
  First item.
  .IP "\(bu" 6
  Second item.

which is definitely fine,
and lists with "=item foo" in just the same way as

  .IP "foo" 6
  Description of foo.
  .IP "bar" 6
  Description of bar.

which is probably also fine for many cases, but maybe not ideal for
the specific case you are quoting.

That man(7) code does not permit inserting a blank output line
between the .IP "foo" and the "Description of foo."
If "foo" is short enough, i.e. less than 6n, it does not even ask
for a line break between the two.

If pod2man(1) wanted blank lines between each =item header and
the subsequent body, it would have to emit something like the
following - right?  That's certainly not the only possibility
way to request such blank lines, but one option:

  foo
  .PP
  .RS 6n
  Description of foo.
  .RE
  .PP
  bar
  .PP
  .RS 6n
  Description of bar.
  .RE

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv