discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Anthony J. Bentley" <anthony@anjbe.name>
Cc: discuss@mandoc.bsd.lv, "Jason A. Donenfeld" <Jason@zx2c4.com>,
	Stephen Gregoratto <dev@sgregoratto.me>
Subject: Re: [PATCH] Fix formatting in wg-quick(8)
Date: Fri, 14 Feb 2020 19:20:48 +0100	[thread overview]
Message-ID: <20200214182048.GH92189@athene.usta.de> (raw)
In-Reply-To: <26710-1581652819.729791@VYCU.Vgnw.Vr5M>

Hi Anthony,

Anthony J. Bentley wrote on Thu, Feb 13, 2020 at 09:00:19PM -0700:

> My attempt is below.

Thanks!

> - There were a few places like this where I wasn't sure if squeezing Ar
>   in there might be overkill:
> 
>     Upon bringing the interface up, this runs
>     .Ql resolvconf -a tun.INTERFACE -m 0 -x
>     and upon bringing it down, this runs
>     .Ql resolvconf -d tun.INTERFACE .

Right, these are somewhat ugly.  Long in-line code examples tend
to look ugly in general, but where they can't be avoided, .Ql is
the right macro to use.  This can hardly be improved without
rewording the text, which you rightly avoided during the conversion.

It is technically possible to use .Ar inside .Ql, but i'd say
it is better avoided.

> - Does the config file support statements across multiple lines (with
>   backslash or some such)? Then we could avoid the ugly wrapping in
>   wg-quick(8)'s EXAMPLES.
> 
> - Wasn't there discussion on the Groff list about moving to title case
>   instead of all caps in section headers? Is that something we want to
>   encourage in downstream manuals?

Not yet, maybe in the future.  Groff now supports the new way.
Support in mandoc is still pending.  Before advertising it widely,
we should make a decision for OpenBSD base.

> - Not sure of my use of Bro/Brc.

Usually, such braces are not needed, we almost never use them in
OpenBSD base.  Then again, you didn't want to change the wording
or the punctuation, and retaining them isn't wrong.  If you want
curlies here, then .Bro is the right macro.

> - The hanging indent in long tag list items seems problematic here.
>   Suggestions?

As any other details, that can be polished after commit.

Ultimately, i would probably recommend something like

  .It Ic set Ar interface Op Ar options
  Set configuration values for the specified
  .Ar interface .
  .Pp
  The options are as follows:
  .Bl -tag -width Ds
  .It Cm fwmark Ar fwmark
  The 32-bit [replace jargon word by an actual description]
  for outgoing packets, either as a decimal integer or as a
  hexadecimal integer starting with
  .Ql 0x .
  The default is 0 [which disables the feature; or even better, say
  more precisely what it means when this feature is "off"].
  The special value
  .Cm off
  is an alias for 0 [or even better, deprecate the duplication
  in the user interface and stop documenting it].
  .It Cm listen-port Ar port
  [A description is missing here what it means.]
  The default is 0, which causes a port to be chosen randomly when
  the interface comes up.
  .It [...]

and so one.  Usually, tagged lists are more readable than long
paragraphs of prose with keywords scattered in the middle.

Yes, i do think the page still needs some work after this initial
conversion, also regarding the content, but that is better done in
multiple steps, each patch focussed on one aspect, with careful
review of each patch.

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

  parent reply	other threads:[~2020-02-14 18:20 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <CAHmME9rVyL+QUhks0J8xOpykb6V+5wKadgowc8bndP=Shi5gyA@mail.gmail.com>
2020-02-11 22:59 ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld
2020-02-12  7:02   ` Jan Stary
2020-02-12 15:06     ` Ingo Schwarze
2020-02-12 15:14     ` Jan Stary
2020-02-12 15:25       ` Ingo Schwarze
2020-02-12 21:44   ` Ingo Schwarze
2020-02-13  4:29     ` Stephen Gregoratto
2020-02-13  4:49       ` [PATCH] Fix formatting in wg-quick(8) Stephen Gregoratto
2020-02-13  8:57         ` Raf Czlonka
2020-02-13 16:31         ` Jason A. Donenfeld
2020-02-13 18:34           ` Ingo Schwarze
2020-02-13 17:57         ` Ingo Schwarze
2020-02-13 18:00           ` Jason A. Donenfeld
2020-02-13 19:34             ` Ingo Schwarze
2020-02-13 19:55               ` Jason A. Donenfeld
2020-02-13 22:28                 ` Ingo Schwarze
2020-02-13 22:38                   ` Jason A. Donenfeld
2020-02-13 22:44                   ` Jan Stary
2020-02-13 23:21                     ` Steffen Nurpmeso
2020-02-14  4:00                   ` Anthony J. Bentley
2020-02-14 11:08                     ` Jason A. Donenfeld
2020-02-14 15:05                       ` Ingo Schwarze
2020-02-14 22:36                       ` Anthony J. Bentley
2020-02-14 18:20                     ` Ingo Schwarze [this message]
2020-02-15  0:45         ` [PATCH v2] Rewrite wg-quick.8 in mdoc Stephen Gregoratto
2020-02-15 19:53           ` Jason A. Donenfeld
2020-02-16 10:32             ` Stephen Gregoratto
2020-02-16 15:52               ` Ingo Schwarze
2020-02-13 16:34     ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld

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=20200214182048.GH92189@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=Jason@zx2c4.com \
    --cc=anthony@anjbe.name \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: [PATCH] Fix formatting in wg-quick(8)' \
    /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

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