-------- 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@xxxxxxxxxxxxx>
To: Qu Wenruo <quwenruo@xxxxxxxxxxxxxx>
Date: 2014年05月18日 20:05
On Sun, May 18, 2014 at 03:04:33PM +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@xxxxxxxxxxxxx>
To: dsterba@xxxxxxx, Qu Wenruo <quwenruo@xxxxxxxxxxxxxx>,
linux-btrfs@xxxxxxxxxxxxxxx, clm@xxxxxx
Date: 2014年05月18日 02:22
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.
I have already encountered problems like that, especially when convert
'btrfs-resize' related things.
But wait for a minute, do we really need the *fascinating* highlight things
in a user documentation?
Yes, absolutely. The formatting is a part of the _meaning_ of the
documentation. Otherwise you're left guessing as to which pieces of
the string of characters are meant to be there literally, and which
pieces have to be replaced by suitable text, and which pieces are
optional.
The most important thing is the content not the format.
My point is that in this case the formatting _is_ a part of the
content.
I choose asciidoc to make developers take less effort on the format things,
not the opposite.
In this point of view, I think asciidoc does things considerately well.
Although the problem you mentioned is true, but it only affects a small part
of the documentation,
compared to the overall benefits, I still consider converting to asciidoc is
worthy.
I'm finding it almost impossible to make it do what I want. I think
in some cases it actually _is_ impossible. This is a truly frustrating
tool that is really not making things simpler, and I can see is going
to lead to even more badly marked up documentation -- simply because
it's too difficult and frustrating to get it right.
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.
From the purpose of documentation and the above explaination, I think the
answer is *Yes*.
Only if you don't care about the typography of the resulting document.
Since you seems really unhappy with the git documentation style, I have
nothing else to say.
I recommended you to send your opinion to git mail list and see what
they respond.
I think it is now upon David to make the decision.
Thanks,
Qu.
If you really think there is a better choice, I will be very happy
to listen, but please consider what I mentioned above and the
privious mail first.
I don't have any real suggestions for alternatives coming from my
experience, other than "not this". I've used docbook for man pages
briefly, many years ago. Looking around on the web, reStructuredText
might be a good option. Personally, I'd like to write docs in LaTeX,
but I'm not sure how easy it is to convert that to man pages.
Hugo.
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
