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:][+/\-]\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.
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
