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

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

[Francis Daly]

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 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.

This patch makes the html docs right, makes the asciidoc docs a bit odd
but consistent with what is there already, and makes the manpages look
OK using docbook-xsl 1.68, but miss a paragraph separator when using 1.69.

For the manpages, current is like

       -A <author_file>
              Read a file with lines on the form

              username = User's Full Name <email@addr.es>

              and use "User's Full Name <email@addr.es>" as the GIT

With this patch, docbook-xsl v1.68 looks like

       -A <author_file>
              Read a file with lines on the form

                      username = User's Full Name <email@addr.es>

              and use "User's Full Name <email@addr.es>" as the GIT author and

while docbook-xsl v1.69 becomes

       -A <author_file>
              Read a file with lines on the form

                        username = User's Full Name <email@addr.es>
              and use "User's Full Name <email@addr.es>" as the GIT author and

The extra indentation is to keep the v1.69 manpage looking sane.

---
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index 57027b4..b0c6d7c 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -99,21 +99,24 @@ If you need to pass multiple options, se
 	CVS by default uses the unix username when writing its
 	commit logs. Using this option and an author-conv-file
 	in this format
-
++
+---------
 	exon=Andreas Ericsson <ae@op5.se>
 	spawn=Simon Pawn <spawn@frog-pond.org>
 
-	git-cvsimport will make it appear as those authors had
-	their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly
-	all along.
-
-	For convenience, this data is saved to $GIT_DIR/cvs-authors
-	each time the -A option is provided and read from that same
-	file each time git-cvsimport is run.
-
-	It is not recommended to use this feature if you intend to
-	export changes back to CVS again later with
-	git-link[1]::git-cvsexportcommit.
+---------
++
+git-cvsimport will make it appear as those authors had
+their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly
+all along.
++
+For convenience, this data is saved to $GIT_DIR/cvs-authors
+each time the -A option is provided and read from that same
+file each time git-cvsimport is run.
++
+It is not recommended to use this feature if you intend to
+export changes back to CVS again later with
+git-link[1]::git-cvsexportcommit.
 
 OUTPUT
 ------
diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt
index 9d38657..b1b87c2 100644
--- a/Documentation/git-svnimport.txt
+++ b/Documentation/git-svnimport.txt
@@ -75,18 +75,21 @@ When importing incrementally, you might 
 
 -A <author_file>::
 	Read a file with lines on the form
++
+------
+	username = User's Full Name <email@addr.es>
 
-	  username = User's Full Name <email@addr.es>
-
-	and use "User's Full Name <email@addr.es>" as the GIT
-	author and committer for Subversion commits made by
-	"username". If encountering a commit made by a user not in the
-	list, abort.
-
-	For convenience, this data is saved to $GIT_DIR/svn-authors
-	each time the -A option is provided, and read from that same
-	file each time git-svnimport is run with an existing GIT
-	repository without -A.
+------
++
+and use "User's Full Name <email@addr.es>" as the GIT
+author and committer for Subversion commits made by
+"username". If encountering a commit made by a user not in the
+list, abort.
++
+For convenience, this data is saved to $GIT_DIR/svn-authors
+each time the -A option is provided, and read from that same
+file each time git-svnimport is run with an existing GIT
+repository without -A.
 
 -m::
 	Attempt to detect merges based on the commit message. This option

-- 
Francis Daly        francis@daoine.org

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

[Jonas Fonseca]

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

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

[Jonas Fonseca]

Asciidoc cannot handle multi-paragraph description list items without the
need for adding special control characters and reindenting all paragraphs
but the first. Workaround it in make-cg-asciidoc so that the documentation
in the script headers can use the more intuitive and readable formatting.

Affected files are cg-patch and cg-commit.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 Documentation/make-cg-asciidoc |   25 ++++++++++++++++++++++++-
 1 files changed, 24 insertions(+), 1 deletions(-)

diff --git a/Documentation/make-cg-asciidoc b/Documentation/make-cg-asciidoc
index 126d4eb..c454062 100755
--- a/Documentation/make-cg-asciidoc
+++ b/Documentation/make-cg-asciidoc
@@ -112,8 +112,31 @@ $DESCRIPTION
 
 OPTIONS
 -------
-$OPTIONS
+
+--
+__END__
+
+# Only indent the first paragraph of multi-paragraph list items.
+multipara=
+echo "$OPTIONS" | while read line; do
+	case "$line" in
+	*::)
+		multipara=
+		;;
+	"")
+		multipara=t
+		;;
+	*)
+		[ "$multipara" ] || line="	$line"
+	esac
+
+	echo "$line"
+done
+
+cat <<__END__
+
 $HELP_OPTIONS
+--
 
 $MISC
 

-- 
Jonas Fonseca