Re: [PATCH] Fix multi-paragraph list items in OPTIONS section

[Jonas Fonseca <fonseca@diku.dk>]

Francis Daly <francis@daoine.org> wrote Mon, Mar 20, 2006:
> On Mon, Mar 20, 2006 at 10:39:46, Jonas Fonseca wrote:
> 
> > Asciidoc cannot handle multi-paragraph description list items without the
> > need for adding special control characters and reindenting all paragraphs
> > but the first. 
> 
> This issue affects the display of current git-cvsimport and
> git-svnimport doc pages. There was a general tidy-up done in
> df8baa42fe4eeb5a021ac262caf601f44d2a5746 last October, but additions
> since then didn't keep the layout.

I think we are only a few people who cares about this and the vast
number of git manpages makes it very time consuming to keep the layout
polished. Personally, I care mostly for the git core manpages. Maybe if
they lived in a separate directory from the git porcelain manpages it
would be easier to get them into a better shape.

> I don't think there is a full "fix" for this; either the html docs are
> ugly (see the -A section in the pages mentioned above as they are now),
> or the asciidoc source files look odd (although that's probably not a
> big problem) or the manpages look a bit funny.

I found the same thing. Getting both good HTML and manpages is not
trivial unless you use only limited and simple markup. Some things
supported by the HTML generator is not available or doesn't turn out as
good in the generated manpages. This was the main reason I decided to
add a special script to strip/convert markup when generating the cg-ref
manpages.

As for the odd looking asciidoc sources, you can always generate a clean
text version. BTW, for lists you can get rid of the '+' continuations
tags by embedding the list in a pair of '--'. It makes the resulting
source a little more readable.

	--
	 - item 1, para 1
	
	item 1, para 2

	 - item 2
	--

-- 
Jonas Fonseca