discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: "Pali Rohár" <pali.rohar@gmail.com>
To: Ingo Schwarze <schwarze@usta.de>
Cc: discuss@mandoc.bsd.lv
Subject: Re: mandoc & perl documentation
Date: Sun, 25 Nov 2018 14:34:26 +0100	[thread overview]
Message-ID: <20181125133426.s77sfsadbkz6jhcl@pali> (raw)
In-Reply-To: <20181124193152.GC16061@athene.usta.de>

[-- Attachment #1: Type: text/plain, Size: 7700 bytes --]

On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote:
> 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?

Yes, seems this is working fine.

> 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

Question is if last 6 lines are correctly translated. Should not it be
typewriter font which has both italic and bold style? Because currently
it is just bold typewriter and not italic.

Has troff, groff or mandoc some sequence of italic bold typewriter font?
It is probably something very unusual as a big Computer Modern font
family does not have such style too.

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

Yes.

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

I'm not sure if it is fine.

Here is simple test.pod file:

$ cat test.pod
=pod

=over

=item *

Description of item1

=item *

Description of item2

=back

=cut

Converting it directly to HTML via pod2html results in:

$ pod2html test.pod
...
<ul>
<li><p>Description of item1</p>
</li>
<li><p>Description of item2</p>
</li>
</ul>
...

But converting it into man and then via mandoc converting it into HTML
results in:

$ pod2man test.pod | ./mandoc -Thtml
...
<div class="manual-text">
<div>&#x00A0;</div>
<dl class="Bl-tag">
  <dt>&#x2022;</dt>
  <dd>Description of item1</dd>
</dl>
<dl class="Bl-tag">
  <dt>&#x2022;</dt>
  <dd>Description of item2</dd>
</dl>
</div>
...

Bullet (&#2022) generated by mandoc is on previous line as description
text. So something is not there fine. I see it in chrome and also in
elinks:

$ pod2man test.pod | ./mandoc -Thtml | elinks -dump
...
   •
           Description of item1

   •
           Description of item2
...

And when I print mandoc output on terminal, then description and bullet
are on the same line:

$ pod2man test.pod | ./mandoc
...
       •   Description of item1

       •   Description of item2
...

So this looks like a problem in mandoc's HTML output.

> 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

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

  reply	other threads:[~2018-11-25 13:34 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-09-13 15:12 Pali Rohár
2018-09-13 15:32 ` Anthony J. Bentley
2018-09-13 15:36   ` Pali Rohár
2018-10-11  7:52 ` Pali Rohár
2018-10-11  8:54   ` Jan Stary
2018-10-23 17:45   ` Ingo Schwarze
2018-10-24  8:03     ` Pali Rohár
2018-10-25  1:51       ` Ingo Schwarze
2018-10-25  8:10         ` Pali Rohár
2018-10-25 21:30           ` Ingo Schwarze
2018-10-26  8:15             ` Pali Rohár
2018-11-24 19:31               ` Ingo Schwarze
2018-11-25 13:34                 ` Pali Rohár [this message]
2018-11-25 18:20                   ` Ingo Schwarze
2018-11-26  8:48                     ` Pali Rohár
2019-02-28 16:45                   ` Ingo Schwarze
2019-03-02 17:09                   ` Ingo Schwarze
2019-01-17  8:02           ` Ingo Schwarze
2018-11-04 20:00         ` Pali Rohár

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20181125133426.s77sfsadbkz6jhcl@pali \
    --to=pali.rohar@gmail.com \
    --cc=discuss@mandoc.bsd.lv \
    --cc=schwarze@usta.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).