From: Derrick Stolee Date: Wed, 22 Aug 2018 01:19:23 GMT Subject: Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc Message-ID: In-Reply-To: On 8/21/2018 5:29 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" writes: > >> From: Derrick Stolee >> >> When viewing commit-graph.txt as a plain-text document, it makes >> sense to keep paragraphs left-padded between bullet points. >> However, asciidoc converts these left-padded paragraphs as monospace >> fonts, creating an unpleasant document. Remove the padding. > That's completely backwards. > > These indented two paragraphs that follow "... the following > property:" do not fall into the same classes of paragraphs as > others. The way the text version makes them stand out by indenting > clearly show these two are what "... the following ..." refers to. > > Perhaps these two would want to become a bulleted list or > something. > >> The "Future Work" section includes a bulleted list of items, and one >> item has sub-items. These do not render properly in asciidoc, so >> remove the sub-list and incorporate them into the paragraph. >> >> Signed-off-by: Derrick Stolee >> --- >> Documentation/technical/commit-graph.txt | 43 +++++++++++------------- > I said I didn't check if commit-graph-format.txt doc format > correctly, but that does not mean you do not have to ;-). I suspect > that most of the contents would become monospaced wall of text, > which is no better than the original text and because only the > headings are typeset in different font, the result actually would be > harder to read than the original. I compared the results of commit-graph-format.txt to pack-format.txt. Since I had based the format of commit-graph-format.txt on that file, the output was remarkably similar (and hence I couldn't find anything to change). > We are not in a hurry to do this during the pre-release period, are > we? My understanding is that the original text documentation files > will be shipped and installed, and they are adequately readable > (correct me if it is not the case). > > Unless we are making the result a lot more readable as the original > text, let's not distract ourselves by rerolling this in too quick > cycles without giving us sufficiently big improvements. No rush! I'll wait until the release calms down for a v3, and read the helpful docs on asciidoc format that Eric shared earlier. Thanks, -Stolee