Re: [PATCH v2 2/2] commit-graph.txt: improve formatting for asciidoc

[Derrick Stolee <stolee@gmail.com>]

On 8/21/2018 5:29 PM, Junio C Hamano wrote:
> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Derrick Stolee <dstolee@microsoft.com>
>>
>> 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 <dstolee@microsoft.com>
>> ---
>>   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