From: Todd Zullinger <tmz@pobox.com>
To: Son Luong Ngoc <sluongng@gmail.com>
Cc: shouryashukla.oo@gmail.com, git@vger.kernel.org,
gitster@pobox.com, newren@gmail.com,
sandals@crustytoothpaste.net
Subject: Re: [PATCH v7 1/4] gitfaq: files in .gitignore are tracked
Date: Tue, 19 May 2020 00:53:01 -0400 [thread overview]
Message-ID: <20200519045301.GY24220@pobox.com> (raw)
In-Reply-To: <CAL3xRKdwOASiGys+7Uu_OA5kBPrTdAURfEw3UQ+rguTXT+C6JQ@mail.gmail.com>
Hi,
Son Luong Ngoc wrote:
> Hey folks,
>
>> Add issue in 'Common Issues' section which addresses the problem of
>> Git tracking files/paths mentioned in '.gitignore'.
>>
>> Signed-off-by: Shourya Shukla <shouryashukla.oo@gmail.com>
>> ---
>> Documentation/gitfaq.txt | 10 ++++++++++
>> 1 file changed, 10 insertions(+)
>>
>> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
>> index 1cf83df118..11d9bac859 100644
>> --- a/Documentation/gitfaq.txt
>> +++ b/Documentation/gitfaq.txt
>> @@ -223,6 +223,16 @@ a file checked into the repository which is a template or set of defaults which
>> can then be copied alongside and modified as appropriate. This second, modified
>> file is usually ignored to prevent accidentally committing it.
>>
>> +[[files-in-.gitignore-are-tracked]]
>
> This does not work for older xmlto(centos6) for whatever reason.
> ```
> # make doc
> ...
> # xmlto -m manpage-normal.xsl -m manpage-bold-literal.xsl -m
> manpage-base-url.xsl man gitfaq.xml
> xmlto: /<git-dir>/Documentation/gitfaq.xml does not validate (status 3)
> xmlto: Fix document syntax or use --skip-validation option
> /<git-dir>/Documentation/gitfaq.xml:3: element refentry: validity
> error : Element refentry content does not follow the DTD, expecting
> (beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link |
> olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ |
> refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1
> refsect1 refsect1 refsect1 variablelist refsect1 refsect1 )
> ```
I ran into this as well. I _think_ this is an asciidoc
issue (but it could be further up the doc tools chain). On
CentOS 6, the asciidoc version is 8.4.5. From earlier in
the make output:
make[1]: Leaving directory `/builddir/build/BUILD/git-2.27.0.rc0'
rm -f gitfaq.html+ gitfaq.html && \
asciidoc -f asciidoc.conf -amanversion=2.27.0.rc0 -amanmanual='Git Manual' -amansource='Git' -b xhtml11 -d manpage -o gitfaq.html+ gitfaq.txt && \
mv gitfaq.html+ gitfaq.html
WARNING: gitfaq.txt: line 245: missing [[files-in-.gitignore-are-tracked]] section
Dropping the "." from the anchor name works around the
failure, which seems like a reasonable thing to do. With
the age of asciidoc and CentOS 6 approaching end-of-life
this November, we wouldn't want to spend too much effort to
work around issues there. But this seems like an easy way
to allow the documentation to continue to build on such old
platforms.
There do appear to be other issues with the asciidoc's
parsing of the anchors, as some of the others are either not
included in the xml and html or are not quite in the place
they should be. I didn't see an obvious reason for that,
but I didn't spend all that long looking over gitfaq.txt
because I imagine there are plenty of minor issues with
asciidoc-8.4.5.
I thought this change in asciidoc might have fixed the
issue:
https://github.com/asciidoc/asciidoc/commit/4ceeb32
But I didn't have any luck after applying that to
asciidoc-8.4.5.
Anyway, here's the quick work-around in patch form.
-- >8 --
Subject: [PATCH] gitfaq: avoid validation error with older asciidoc
When building with asciidoc-8.4.5 (as found on CentOS/Red Hat 6), the
period in the "[[files-in-.gitignore-are-tracked]]" anchor is not
properly parsed as a section:
WARNING: gitfaq.txt: line 245: missing [[files-in-.gitignore-are-tracked]] section
The resulting XML file fails to validate with xmlto:
xmlto: /git/Documentation/gitfaq.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
/git/Documentation/gitfaq.xml:3: element refentry: validity error :
Element refentry content does not follow the DTD, expecting
(beginpage? , indexterm* , refentryinfo? , refmeta? , (remark | link
| olink | ulink)* , refnamediv+ , refsynopsisdiv? , (refsect1+ |
refsection+)), got (refmeta refnamediv refsynopsisdiv refsect1
refsect1 refsect1 refsect1 variablelist refsect1 refsect1 )
Document /git/Documentation/gitfaq.xml does not validate
Let's avoid breaking users of platforms which ship an old version of
asciidoc, since the cost to do so is quite low.
Reported-by: Son Luong Ngoc <sluongng@gmail.com>
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
Documentation/gitfaq.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index 370d62dae4..9cd7a592ac 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -223,7 +223,7 @@ a file checked into the repository which is a template or set of defaults which
can then be copied alongside and modified as appropriate. This second, modified
file is usually ignored to prevent accidentally committing it.
-[[files-in-.gitignore-are-tracked]]
+[[files-in-gitignore-are-tracked]]
I asked Git to ignore various files, yet they are still tracked::
A `gitignore` file ensures that certain file(s) which are not
tracked by Git remain untracked. However, sometimes particular
--
2.26.1
-- >8 --
--
Todd
next prev parent reply other threads:[~2020-05-19 4:53 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-15 17:32 [PATCH v7 1/4] gitfaq: files in .gitignore are tracked Son Luong Ngoc
2020-05-19 4:53 ` Todd Zullinger [this message]
-- strict thread matches above, loose matches on Subject: below --
2020-05-06 17:11 Shourya Shukla
2020-05-06 18:15 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200519045301.GY24220@pobox.com \
--to=tmz@pobox.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=newren@gmail.com \
--cc=sandals@crustytoothpaste.net \
--cc=shouryashukla.oo@gmail.com \
--cc=sluongng@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).