Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On Tue, May 20, 2014 at 08:34:19AM +0800, Qu Wenruo wrote:
Proposed changes:
- format all subcommands as bold instead of italic ('' - **)
- add all missing ...
- find a way how to add '...' around ... (xsl or sed or whatever)
Does that work for you?
That is OK for me, I'll investigate it.
Should I send a new patchset or just delta patches upon the current base?
Don't bother, patches sent yesterday.
--
To unsubscribe from this list: send the line unsubscribe linux-btrfs in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On 05/17/2014 01:43 PM, 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:][+/\-]\fIsize\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. Are there issues with the asciidoc form outside of the command summary line? The reason I ask is that all of these tools have tradeoffs. If asciidoc makes our documentation easier to update and easier to keep up to date, I'm willing to trade that for the perfect summary line. I think the easiest way to add clarity to the summary (in any markup language) is by providing examples. Italics and bolds definitely help, but examples always win. -chris -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote: 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:][+/\-]\fIsize\fP[gkm]|[\fIdevid\fP:]\fImax path\fP I think we can restore the formatting with asciidoc. The line above would become: *btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]'max path' or with bold max *btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]*max* 'path' I was first worried that this will not be possible due to limitations of asciidoc markup but as this turned out not be true, I'd rather spend the boring time to keep the formatting as before. My personal feeling about the enriched formatting is that the commands stand out of the text and are easier to catch (as you've mentioned somewhere in the thread). -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On Mon, May 19, 2014 at 04:01:23PM +0200, David Sterba wrote:
On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote:
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:][+/\-]\fIsize\fP[gkm]|[\fIdevid\fP:]\fImax path\fP
I think we can restore the formatting with asciidoc.
The line above would become:
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]'max path'
or with bold max
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]*max* 'path'
The correct base string should read
btrfs filesystem resize [devid:][+/-]size[kgm]|[devid:]max path
ie. add .. around devid and size. That way it's copy-paste-ready.
In this case the italic/underlined text does not IMO add much value.
My personal feeling about the enriched formatting is that the commands
stand out of the text and are easier to catch (as you've mentioned
somewhere in the thread).
The bolded subcommand name seems to be sufficent.
The files are processed by XSL, I think it should be possible to apply
some transformation that would add '...' around ... automatically
instead of making everybody write that.
Proposed changes:
- format all subcommands as bold instead of italic ('' - **)
- add all missing ...
- find a way how to add '...' around ... (xsl or sed or whatever)
Does that work for you?
--
To unsubscribe from this list: send the line unsubscribe linux-btrfs in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
Original Message
Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and
man page for each btrfs subcommand.
From: David Sterba dste...@suse.cz
To: Hugo Mills h...@carfax.org.uk, Qu Wenruo
quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@fb.com
Date: 2014年05月19日 22:33
On Mon, May 19, 2014 at 04:01:23PM +0200, David Sterba wrote:
On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote:
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:][+/\-]\fIsize\fP[gkm]|[\fIdevid\fP:]\fImax path\fP
I think we can restore the formatting with asciidoc.
The line above would become:
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]'max path'
or with bold max
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]*max* 'path'
The correct base string should read
btrfs filesystem resize [devid:][+/-]size[kgm]|[devid:]max path
ie. add .. around devid and size. That way it's copy-paste-ready.
In this case the italic/underlined text does not IMO add much value.
It is completely OK for me.
Since the base string is copy-paste-ready, it would add any extra effort
to add other markup.
My personal feeling about the enriched formatting is that the commands
stand out of the text and are easier to catch (as you've mentioned
somewhere in the thread).
The bolded subcommand name seems to be sufficent.
The files are processed by XSL, I think it should be possible to apply
some transformation that would add '...' around ... automatically
instead of making everybody write that.
Proposed changes:
- format all subcommands as bold instead of italic ('' - **)
- add all missing ...
- find a way how to add '...' around ... (xsl or sed or whatever)
Does that work for you?
That is OK for me, I'll investigate it.
Should I send a new patchset or just delta patches upon the current base?
Thanks,
Qu
--
To unsubscribe from this list: send the line unsubscribe linux-btrfs in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
Original Message Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand. From: Hugo Mills h...@carfax.org.uk To: dste...@suse.cz, Qu Wenruo quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@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:][+/\-]\fIsize\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) 2) Make the documenation more general purpose. (Why choose asciidoc) Not only generating man pages, but also html/pdf, much like git. 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. 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. Due to the above 3 reasons, I think throwing all markup in synopsis is a better choice. 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 -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
Original Message Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand. From: Hugo Mills h...@carfax.org.uk To: dste...@suse.cz, Qu Wenruo quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@fb.com 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:][+/\-]\fIsize\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? The most important thing is the content not the format. 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. 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*. 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. Thanks, Qu. 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 -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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 h...@carfax.org.uk To: dste...@suse.cz, Qu Wenruo quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@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:][+/\-]\fIsize\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
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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 h...@carfax.org.uk To: dste...@suse.cz, Qu Wenruo quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@fb.com 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:][+/\-]\fIsize\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. 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
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On 2014/05/18 02:05 PM, Hugo Mills wrote: On Sun, May 18, 2014 at 03:04:33PM +0800, Qu Wenruo wrote: 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. What I have read so far indicates that LaTeX is the simplest most beautiful way to create portable documentation - and that exporting to a man page is simple. I can't vouch for it except to say that it is worth investigating. -- __ Brendan Hide http://swiftspirit.co.za/ http://www.webafrica.co.za/?AFF1E97 -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
Original Message Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand. From: Hugo Mills h...@carfax.org.uk To: Qu Wenruo quwen...@cn.fujitsu.com 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 h...@carfax.org.uk To: dste...@suse.cz, Qu Wenruo quwen...@cn.fujitsu.com, linux-btrfs@vger.kernel.org, c...@fb.com 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:][+/\-]\fIsize\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
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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:][+/\-]\fIsize\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. 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 --- There isn't a noun that can't be verbed. --- signature.asc Description: Digital signature
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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:][+/\-]\fIsize\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 --- signature.asc Description: Digital signature
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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. btrfs-progs: Convert man page for btrfs-dedup. As dedup is not yet merged in kernel, the docs will not be part of the branch (but will be otherwise present in the integration). btrfs-progs: Convert man page for btrfsck I've skipped the patch adding btrfsck and linked to 'btrfs-check' instead, patch will follow. -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On Wed, Apr 02, 2014 at 09:24:10AM -0400, Chris Mason wrote: On 04/02/2014 04:29 AM, Qu Wenruo wrote: Convert the old btrfs man pages to new asciidoc and split the huge btrfs man page into subcommand man page. The asciidoc style and Makefile things are mostly simplified from git Documentation, which only supports man page output and remove html output, since html output is somewhat overkilled for btrfs. Thanks for doing this. I've never liked roff, but I'll give people on the list a chance to complain before taking this one. Moving to asciidoc is definitely the right thing to do. Dave's also been moving the xfs docs in this direction. http://oss.sgi.com/cgi-bin/gitweb.cgi?p=xfs/xfs-documentation.git;a=summary - z -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On 04/02/2014 04:29 AM, Qu Wenruo wrote: Convert the old btrfs man pages to new asciidoc and split the huge btrfs man page into subcommand man page. The asciidoc style and Makefile things are mostly simplified from git Documentation, which only supports man page output and remove html output, since html output is somewhat overkilled for btrfs. Thanks for doing this. I've never liked roff, but I'll give people on the list a chance to complain before taking this one. -chris -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
On Wed, Apr 02, 2014 at 09:24:10AM -0400, Chris Mason wrote: On 04/02/2014 04:29 AM, Qu Wenruo wrote: Convert the old btrfs man pages to new asciidoc and split the huge btrfs man page into subcommand man page. The asciidoc style and Makefile things are mostly simplified from git Documentation, which only supports man page output and remove html output, since html output is somewhat overkilled for btrfs. Thanks for doing this. I've never liked roff, but I'll give people on the list a chance to complain before taking this one. 1970's called and it wants it troff back :) More seriously, thanks much for this patch, it makes the source man pages easier to read and to edit, which is a great thing for keeping them more up to date. +10 here. Marc -- A mouse is a device used to point at the xterm you want to type in - A.S.R. Microsoft is to operating systems what McDonalds is to gourmet cooking Home page: http://marc.merlins.org/ | PGP 1024R/763BE901 -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand.
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. Excellent! The asciidoc style and Makefile things are mostly simplified from git Documentation, which only supports man page output and remove html output, since html output is somewhat overkilled for btrfs. Well, I've been thinking about automatically pushing the man pages to wiki, with asciidoc it would be much easier, the formatting capabilities are better than what *roff provides. 1) More human-readable raw documentations. The roff grammar is not so easy to read, especially mixed with a lot of special words. 2) Easier to modify man page. The old huge btrfs man page makes it hard to maintain. It's common that some one adds some new options, but only modifies the detailed options but not the 'SYNOPSIS' section. I hope both points will encourage more people to contribute to the documentation. -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
