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

From: Jonas Fonseca <fonseca@diku.dk>
Date: Mar 22, 2006, 20:03 UTC
Message-ID: <20060322200327.GA31324@diku.dk>
In-Reply-To: <20060320104118.GA32151@craic.sysops.org>

Francis Daly <francis@daoine.org> wrote Mon, Mar 20, 2006:

Show 10 quoted lines

> 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