discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Pali Rohár" <pali.rohar@gmail.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: mandoc & perl documentation
Date: Thu, 25 Oct 2018 23:30:27 +0200	[thread overview]
Message-ID: <20181025213027.GA41690@athene.usta.de> (raw)
In-Reply-To: <20181025081035.qo3i4vrrkm2nwnbf@pali>

Hi Pali,

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:

> In perl documentation it is very common to put code examples
> into SYNOPSIS

That is abuse and should not be done.

The SYNOPSIS must only contain authoritative information
and must be as concise as possible.
Examples belong below EXAMPLES and nowhere else.

> and code examples should be really in monospaced font.

Yes, that is true.

> 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 see that output of monospaced font on debian manpage server is put
> into double quotes.

Well, that is pod2man(2)'s doing.  At many places, it says things like

  .ie n .IP """strict refs""" 6
  .el .IP "\f(CWstrict refs\fR" 6

Translating that into plain English in case you are not too familiar
with the admittedly weird roff(7) syntax:

  If we are formatting for non-typesetting output, emit a list tag
  starting with one '"' character, containing the words "strict
  refs", and ending with a matching quote, in a field 6 columns wide;
  otherwise, i.e. when formatting for typeset output (like PostScript
  or PDF), switch to constant width font for the tag, print the
  words "strict refs", and switch to roman font, again in a field
  6 columns wide (with no quotes in this case).

Mandoc always formats for non-typesetting output, so it always gets
the quotes and never switches to constant width font for this
particular input.

This is one of the relatively rare cases where pod2man(1) is doing
something that is a bad idea.  First, in my personal opinion, manual
pages should not use if-statements; though some might argue that in
this case, to get the quotes for terminal output, it might be justified.
But i think the quotes are irrelevant: Because the "strict ref" is
located in a list tag, it is already obvious it is a syntax element
being defined and not some running English text.

Even more importantly, even if pod2man(1) insists on the .ie and
on the quotes, then it should at least say

  .ie n .IP """\f(CWstrict refs\f(CW""" 6
  .el .IP "\f(CWstrict refs\fR" 6

Some non-typesetting output devices (like mandoc HTML) do support
constant width font, so why not tell them?  In particular given
that the running text right below heavily uses \f(CW no matter what:

  This generates a compile-time error if you access a variable that
  was neither explicitly declared (using any of \f(CW\*(C`my\*(C'\fR,
  \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`state\*(C'\fR, ...

You said you could possibly help to improve pod2man(1).  Do you
think you could ask them to get this particular kind of .IP fixed?
Preferably to simply

  .IP "\f(CWstrict refs\fR" 6

or if they really want quotes even in .IP to

  .IP "\f(CW\*(C`strict refs\*(C'\fR" 6

either way without any "if", or if they totally insist at least to

  .ie n .IP """\f(CWstrict refs\f(CW""" 6
  .el .IP "\f(CWstrict refs\fR" 6

> 1) It is still needed to double quote text which is written in
> monospaced font?

In .IP, I don't think so.  I think it was never needed, see above.
But that would have to be changed in pod2man(1), not in mandoc(1).

And no, i cannot change mandoc(1) to attempt rendering for real
typesetting devices.  Code protected by ".if t" or ".ie n .el"
typically uses even more scary low-level roff(7) features that
mandoc doesn't, and can hardly, implement.

> Compare first sentence in DESCRIPTION https://man.openbsd.org/strict and
> https://metacpan.org/pod/strict On man.openbsd is word "strict" put into
> double quotes, but on metacpan not.

That is again a choice by pod2man(1), which this time makes more sense.
The preamble emitted by pod2man(1) defines a strings named "C`" and "C'"
as empty string on typesetting devices and as quotes on non-typesetting
devices, and the main code emitted by pod2man(1) then uses the
idioms "\f(CW\*(C" and "\*(C'\fR" to begin and end in-line code snippets,
such that those get typeset in proportional font without quotes on
typesetting devices and such that they get quoted on terminals -
and, collaterally, *both* set in proportional font and quoted on
non-typesetter devices that support proportional font like mandoc(1)
HTML output.

I think little can be done here.  You probably do not want to take
away *these* quotes because that would make the word look like
running text on the terminal.  And there is no way for the document
to query whether monospace font looks different from the default
font on the current output device, so the ".if n" kludge is half
reasonable.

> 2) When I try to select any code block (e.g. SYNOPSIS or "strict subs"
> section) on man.openbsd, then every code line is prefixed by four
> spaces. When I select it on metacpan, then there is no leading space. Is
> there particular reason for it?

The perlpod(1) manual defines:

   Verbatim Paragraph
       Verbatim paragraphs are usually used for presenting a codeblock
       or other text which does not require any special parsing or
       formatting, and which shouldn't be wrapped.

       A verbatim paragraph is distinguished by having its first
       character be a space or a tab.  (And commonly, all its lines
       begin with spaces and/or tabs.)  It should be reproduced
       exactly, with tabs assumed to be on 8-column boundaries.

The source code of the strict(3p) manual looks like this:

  $ less /usr/src/gnu/usr.bin/perl/lib/strict.pm
  [...]
  =head1 SYNOPSIS

      use strict;

      use strict "vars";
      use strict "refs";
      use strict "subs";
  [...]

So the four space indentation is in the source code.  It's not
totally clear to me what "reproduced exactly" is supposed to mean,
but pod2man(1)'s interpretation that this whitespace should be
preserved doesn't seem totally unreasonable.  It translates
to man(7) as follows:

  $ less $(man -w strict)
  [...]
  .SH "SYNOPSIS"
  .IX Header "SYNOPSIS"
  .Vb 1
  \&    use strict;
  \&
  \&    use strict "vars";
  \&    use strict "refs";
  \&    use strict "subs";
  [...]

I'm not convinced it would be better for pod2man(1) to strip this
whitespace because on the terminal, the code block would not be
distinguished from running text, neither by font nor by indentation.

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

But you are right that there should be vertical spacing *before*
the list tag.  However, that is very hard to fix in mandoc.css;
the CSS code for ".Bl-tag > dt" (using float) is already excessively
complicated and only barely works.  It is not possible to add some
margin-top to it without breaking it.  Numerous attempts of many
people to improve it have failed.  At EuroBSDCon 2018, i met a
colleague who talked about some new CSS feature that makes formatting
of tagged lists work better if you want short tags left of the body
and long tags above the body.  He promised to send me details, but
didn't come back to me yet.

For now, i have made a TODO entry.

Yours,
  Ingo


Log Message:
-----------
in -man -Thtml, vertical spacing is required before .IP

Modified Files:
--------------
    mandoc:
        TODO

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /home/cvs/mandoc/mandoc/TODO,v
retrieving revision 1.273
retrieving revision 1.274
diff -LTODO -LTODO -u -p -r1.273 -r1.274
--- TODO
+++ TODO
@@ -397,6 +397,12 @@ are mere guesses, and some may be wrong.
    it does seem cleaner.)
   loc **  exist **  algo *  size *  imp ***
 
+- .IP wants vertical spacing before itself;
+  currently, it is formatted like .Bl -compact.
+  Fixing this requires getting rid of the "float"
+  in the CSS for .Bl-tag first.
+  Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
+
 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
   loc ** exist ** algo ** size * imp ***
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2018-10-25 21:30 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 [this message]
2018-10-26  8:15             ` Pali Rohár
2018-11-24 19:31               ` Ingo Schwarze
2018-11-25 13:34                 ` Pali Rohár
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=20181025213027.GA41690@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=pali.rohar@gmail.com \
    /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).