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: 5729 bytes --]

On Sun, May 18, 2014 at 02:51:39PM +0800, Qu Wenruo wrote:
> 
> -------- Original Message --------
> Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man
> page for each btrfs subcommand.
> From: Hugo Mills <hugo@carfax.org.uk>
> To: dsterba@suse.cz, Qu Wenruo <quwenruo@cn.fujitsu.com>,
> linux-btrfs@vger.kernel.org, clm@fb.com
> Date: 2014年05月18日 01:43
> >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
> Yes, When I convert man pages to asciidoc docs, I have already realized the
> problem.
> As mentioned in first patch, most things including the Makefile is 'stolen'
> from git,
> which means I also apply the git way to deal with the all 'useful' markups,
> *just throw them away* .
> >
> >    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.
> As I mentions above, it's meant to be like this, without extra markup just
> like git.
> 
> I choose asciidoc and the git documentation style for the following purpose:
> 
> 1) Split up the huge 'btrfs' man page. (Main purpose of the patchset)
> 
> The 'btrfs' man page is so huge that the synopsis is serveral pages long,
> force developers to edit man page twice(one for synopsis and one for
> command).
> This makes editing frustrating and easy to make things inconsistent.
> (serveral synopsis and command description are already inconsistent)

   I don't have a problem with that, but it's irrelevant to my point.

> 2) Make the documenation more general purpose. (Why choose asciidoc)
> 
> Not only generating man pages, but also html/pdf, much like git.

   I have no objections at all to that either. It's a great idea. But
again, it's orthogonal to my main point here, which is that we've lost
useful semantics, because the markup _is_ part of the meaning of the
document.

> 3) Make the original txt more human readable (Why choose git style)
> 
> I can use the old markup method but after doing that I realize if you read a
> document full of
> markups, the markups have alread lost their meaning.
> 
> If using too many markup, there will be other problems:
>     3.1) making the synopsis in original txt too long
> 
>             This will make both developer and reviewer harder to
> edit/review.
>             I choose asciidoc to reduce the hard-to-understand groff
> grammar, if these \fX are
>             just converted to ' or `, IMO the cost is still not cut.

   I don't think we should be throwing away meaning just because it
makes things shorter in the source.

>     3.2) the markup is not so highlighted if every thing is highlighted
> 
>             So I choose only to highlight really important things, since
> with all the bold and itatlic
>             things full of the page, there is no difference between all
> normal formatted text.

   I'm only talking about two things: the syntactic summaries, where
we need to distinguish between literals, placeholders and descriptive
elements like []; and "command text" where we distinguish between the
descriptive English text and the stuff you type. This second point is
particularly important for us because so many of our commands consist
of recognisable English words strung together, and having the literal
commands shown in a distinctive style (typically a monospace font)
helps enormously with parsing the text when reading at speed.

> Due to the above 3 reasons, I think throwing all markup in synopsis is a
> better choice.

   I disagree strongly.

   Hugo.

> Thanks,
> Qu
> >
> >    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
   --- Two things came out of Berkeley in the 1960s: LSD and Unix. ---   
                       This is not a coincidence.                        

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