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