Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.

[Hugo Mills <hugo@carfax.org.uk>]

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

On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote:
> On Wed, Apr 16, 2014 at 07:12:19PM +0200, David Sterba wrote:
> > On Wed, Apr 02, 2014 at 04:29:11PM +0800, Qu Wenruo wrote:
> > > Convert the old btrfs man pages to new asciidoc and split the huge
> > > btrfs man page into subcommand man page.
> > 
> > I'm merging this patchset into the base series of integration because
> > several patches need to update the docs and it's no longer feasible to
> > keep it in a separate branch from the patches.
> 
>    I've just been poking around in the docs for a completely different
> reason, and I think there's a fairly serious problem (well, as serious
> as problems get with documentation).
> 
>    Take, for example, the format for btrfs fi resize:
> 
> 'resize' [devid:][+/-]<size>[gkm]|[devid:]max <path>::
> 
>    Now, this has just thrown away all of the useful markup which
> indicates the semantics of the command. The asciidoc renders all of
> that text literally and unformatted, making alphasymbolic(*) soup of
> the docs. Compare this to the old roff man page:
> 
> \fBbtrfs\fP \fBfilesystem resize\fP [\fIdevid\fP:][+/\-]\fI<size>\fP[gkm]|[\fIdevid\fP:]\fImax <path>\fP
> 
>    This isn't perfect -- we're missing a \fB around the "max" -- but
> it has text in bold(⁑) and italics(⁂) and neither(☃). I've just looked
> at some of the other pages, and they've also got similar typographical
> problems. This is a lot of fiddly tedious work to get it right, and if
> it doesn't get done now in the initial commit, then we're going to end
> up with poor examples copied for every new feature or docs update,
> making the problem worse before anyone does the work to make it
> better.

   Oh, and asciidoc appears to be the most horrible capricious
inconsistent parser in existence. I've just spent 5 minutes getting
this one line of text to do what I want it to:

=====
__N__**c**[\[_Mmin_**-**]__Mmax__**s**[_P_**p**]]
=====

   I had to run through the list of block quote operators one at a
time in order to find the one I needed for this (the =====); it's
still not indenting it correctly on the resulting man page.

   Note also the fun things like the fact that [[]] is special, so you
have to quote the opening part of it -- but if you try quoting the
first [ with a \ you get a literal \[ in the output. You get the right
output from quoting the *second* [ only.

   The Nc can only be italicised and emboldened properly with __ and
** because _ and * require whitespace around them in order to work
(seriously, WTF?). However, we can't be consistent with that in the
_Mmin_**-** because the quoted \[ appears to count as whitespace, so
using __Mmin__ gives us a leading literal _. The closing __ appears to
close the single opening _ correctly in that case, though.

   Seriously, this is meant to be _easy_ to use? I think I'd rather
type docbook by hand that have to struggle with this. Even the troff
macros for man pages are simpler to get right.

   Hugo.

>    Hugo.
> 
> (*) Or possibly alphashambolic. :)
> (⁑) For literal text
> (⁂) For variables that require substitution by the user
> (☃) For structural syntax indicators such as [] for optional parts, |
>     for alternation and ... to indicate optional continuation of a list
> 

-- 
=== Hugo Mills: hugo@... carfax.org.uk | darksatanic.net | lug.org.uk ===
  PGP key: 65E74AC0 from wwwkeys.eu.pgp.net or http://www.carfax.org.uk
       --- Great oxymorons of the world, no. 1: Family Holiday ---       

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 811 bytes --]