[PATCH] Documentation: Fix build failure of docs.

[PATCH] Documentation: Fix build failure of docs.

[Saikiran Madugula]

This patch fixes the build failure due to what seems to be extraneous
characters, "+++" in the git-filter-branch.txt file.

$make man

...

ASCIIDOC git-filter-branch.xml
    XMLTO git-filter-branch.1
xmlto: input does not validate (status 1)
/home/bobthe/git.kernel.org/git/Documentation/git-filter-branch.xml:435:
parser error : PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone
                                    ^
/home/bobthe/git.kernel.org/git/Documentation/git-filter-branch.xml:435:
parser error : PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone
                                      ^
make[1]: *** [git-filter-branch.1] Error 1
make[1]: Leaving directory
`/home/bobthe/git.kernel.org/git/Documentation'
make: *** [man] Error 2

...

Signed-off-by: Saikiran Madugula <hummerbliss@gmail.com>
---
 Documentation/git-filter-branch.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index ab527b5..8a261c7 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -364,7 +364,7 @@ objects until you tell it to.  First make sure that:
 Then there are two ways to get a smaller repository.  A safer way is
 to clone, that keeps your original intact.
 
-* Clone it with `git clone +++file:///path/to/repo+++`.  The clone
+* Clone it with `git clone file:///path/to/repo`.  The clone
   will not have the removed objects.  See linkgit:git-clone[1].  (Note
   that cloning with a plain path just hardlinks everything!)
 
-- 
1.5.6.3

Re: [PATCH] Documentation: Fix build failure of docs.

[Thomas Rast]

Saikiran Madugula wrote:
> This patch fixes the build failure due to what seems to be extraneous
> characters, "+++" in the git-filter-branch.txt file.
[...]
> ASCIIDOC git-filter-branch.xml
>     XMLTO git-filter-branch.1
> xmlto: input does not validate (status 1)
> /home/bobthe/git.kernel.org/git/Documentation/git-filter-branch.xml:435:
> parser error : PCDATA invalid Char value 7
> Clone it with <literal>git clone +++0+++</literal>.  The clone

NAK.  Presumably you are using an asciidoc 8.x?  Please check if
saying

  make ASCIIDOC8=Yes man

fixes the problem.  Read the comments in Documentation/Makefile for
advice on what precise combination of options you should use.  Also,
if you do not want to actually work on docs

  make quick-install-man

is a much less painful way to get manpages (in this case, from Junio's
'man' branch that has preformatted manpages for 'master').

I put the +++ in there to stop the version I used at the time from
rendering the closing backtick as part of the URL and garbling the
entire paragraph in the process.  To be precise, with asciidoc 8.2.7
and without the +++ I get

  Clone it with <tt>git clone <a href="file:///path/to/repo</tt">file:///path/to/repo</tt</a>>.

in the HTML output.  Note the nested tags.  (With asciidoc 8.4.5 the
problem appears to be fixed.)

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH] Documentation: Fix build failure of docs.

[Saikiran Madugula]

OOps, forgot to cc vger.kernel.org

Thomas Rast wrote:
> NAK.  Presumably you are using an asciidoc 8.x?  Please check if
> saying
> 
>   make ASCIIDOC8=Yes man
> 
> fixes the problem.  Read the comments in Documentation/Makefile for
> advice on what precise combination of options you should use.  Also,
> if you do not want to actually work on docs
> 
>   make quick-install-man
> 
> is a much less painful way to get manpages (in this case, from Junio's
> 'man' branch that has preformatted manpages for 'master').

My asciidoc version is 8.4.1. Yes "make ASCIIDOC8=yes" seems to have built with
out any problems. Thanks for quick-install-man tip, I should have read till the
end of INSTALL document  :) .
> 
> I put the +++ in there to stop the version I used at the time from
> rendering the closing backtick as part of the URL and garbling the
> entire paragraph in the process.  To be precise, with asciidoc 8.2.7
> and without the +++ I get
> 
>   Clone it with <tt>git clone <a href="file:///path/to/repo</tt">file:///path/to/repo</tt</a>>.
> 
> in the HTML output.  Note the nested tags.  (With asciidoc 8.4.5 the
> problem appears to be fixed.)
> 

People would start using latest versions of ascii doc which has no problems,
wouldn't it be better if the default compile options suit them ? Also, it would
be good if "make install man", would do "quick-install-man" as default to
prevent users from the painful compilation of manpages everytime they try to
install latest git.

Re: [PATCH] Documentation: Fix build failure of docs.

[Michael J Gruber]

Saikiran Madugula venit, vidit, dixit 28.07.2009 18:39:
> OOps, forgot to cc vger.kernel.org
> 
> Thomas Rast wrote:
>> NAK.  Presumably you are using an asciidoc 8.x?  Please check if
>> saying
>>
>>   make ASCIIDOC8=Yes man
>>
>> fixes the problem.  Read the comments in Documentation/Makefile for
>> advice on what precise combination of options you should use.  Also,
>> if you do not want to actually work on docs
>>
>>   make quick-install-man
>>
>> is a much less painful way to get manpages (in this case, from Junio's
>> 'man' branch that has preformatted manpages for 'master').
> 
> My asciidoc version is 8.4.1. Yes "make ASCIIDOC8=yes" seems to have built with
> out any problems. Thanks for quick-install-man tip, I should have read till the
> end of INSTALL document  :) .
>>
>> I put the +++ in there to stop the version I used at the time from
>> rendering the closing backtick as part of the URL and garbling the
>> entire paragraph in the process.  To be precise, with asciidoc 8.2.7
>> and without the +++ I get
>>
>>   Clone it with <tt>git clone <a href="file:///path/to/repo</tt">file:///path/to/repo</tt</a>>.
>>
>> in the HTML output.  Note the nested tags.  (With asciidoc 8.4.5 the
>> problem appears to be fixed.)
>>
> 
> People would start using latest versions of ascii doc which has no problems,
> wouldn't it be better if the default compile options suit them ? Also, it would
> be good if "make install man", would do "quick-install-man" as default to
> prevent users from the painful compilation of manpages everytime they try to
> install latest git.

"make install" does not build any documentation at all, so that should
be no source of pain.

The user decides which we to go: install-man or quick-install-man.

Having the defaults set up so that recent "mainstream" versions of the
tool chain work without extra options may sound like a good idea - but
that would mean changing options again and again. I think we should do
this for major milestones (say git 1.7).

Michael

Re: [PATCH] Documentation: Fix build failure of docs.

[Saikiran Madugula]

Michael J Gruber wrote:
> Saikiran Madugula venit, vidit, dixit 28.07.2009 18:39:
>>>
>> People would start using latest versions of ascii doc which has no problems,
>> wouldn't it be better if the default compile options suit them ? Also, it would
>> be good if "make install man", would do "quick-install-man" as default to
>> prevent users from the painful compilation of manpages everytime they try to
>> install latest git.
> 
> "make install" does not build any documentation at all, so that should
> be no source of pain.
> 
> The user decides which we to go: install-man or quick-install-man.
> 
> Having the defaults set up so that recent "mainstream" versions of the
> tool chain work without extra options may sound like a good idea - but
> that would mean changing options again and again. I think we should do
> this for major milestones (say git 1.7).
> 
> Michael
Sure.