[PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning

[PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Nguyễn Thái Ngọc Duy]

We support backslash escape, but we hide the details behind the phrase
"a shell glob suitable for consumption by fnmatch(3)". So it may not
be obvious how one can get literal # or ! at the beginning of a pattern.
Add a few lines on how to work around the magic characters.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Asciidoc 8.2.6 does not like me writing
 "Put \# if you need a literal #.." so I go with "backslash" and
 "hash" instead. `\!` displays fine both in man page and html format.
 '!' changed to `!` because it looks clearer in monospace.

 Documentation/gitignore.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 96639e0..8c03ed4 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -74,11 +74,14 @@ PATTERN FORMAT
    for readability.
 
  - A line starting with # serves as a comment.
+   Put a backslash in front of the first hash for the patterns
+   that start with a hash.
 
- - An optional prefix '!' which negates the pattern; any
+ - An optional prefix `!` which negates the pattern; any
    matching file excluded by a previous pattern will become
    included again.  If a negated pattern matches, this will
-   override lower precedence patterns sources.
+   override lower precedence patterns sources. Use `\!` if
+   you need a literal `!` at the beginning of the pattern.
 
  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find
-- 
1.7.12.1.406.g6ab07c4

Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Philip Oakley]

From: "Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>
> We support backslash escape, but we hide the details behind the phrase
> "a shell glob suitable for consumption by fnmatch(3)". So it may not
> be obvious how one can get literal # or ! at the beginning of a 
> pattern.
> Add a few lines on how to work around the magic characters.
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
> Asciidoc 8.2.6 does not like me writing
> "Put \# if you need a literal #.." so I go with "backslash" and
> "hash" instead. `\!` displays fine both in man page and html format.
> '!' changed to `!` because it looks clearer in monospace.

Why not put the backslash-hash in back quotes as well to give the same 
look/feel consistency?

>
> Documentation/gitignore.txt | 7 +++++--
> 1 file changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> index 96639e0..8c03ed4 100644
> --- a/Documentation/gitignore.txt
> +++ b/Documentation/gitignore.txt
> @@ -74,11 +74,14 @@ PATTERN FORMAT
>    for readability.
>
>  - A line starting with # serves as a comment.

+  A line starting with `#` serves as a comment.

> +   Put a backslash in front of the first hash for the patterns
> +   that start with a hash.
>
+   Use `\#` if you need a literal `#` at the beginning of the pattern.

> - - An optional prefix '!' which negates the pattern; any
> + - An optional prefix `!` which negates the pattern; any
>    matching file excluded by a previous pattern will become
>    included again.  If a negated pattern matches, this will
> -   override lower precedence patterns sources.
> +   override lower precedence patterns sources. Use `\!` if
> +   you need a literal `!` at the beginning of the pattern.
>
>  - If the pattern ends with a slash, it is removed for the
>    purpose of the following description, but it would only find
> -- 
> 1.7.12.1.406.g6ab07c4

Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Nguyen Thai Ngoc Duy]

On Sat, Oct 6, 2012 at 6:33 PM, Philip Oakley <philipoakley@iee.org> wrote:
>> Asciidoc 8.2.6 does not like me writing
>> "Put \# if you need a literal #.." so I go with "backslash" and
>> "hash" instead. `\!` displays fine both in man page and html format.
>> '!' changed to `!` because it looks clearer in monospace.
>
>
> Why not put the backslash-hash in back quotes as well to give the same
> look/feel consistency?

Because asciidoc does not like \#, '\#' nor `\#`. It just shows \
without # and I don't want to master asciidoc just to make it show \#.
-- 
Duy

Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Jeff King]

On Sat, Oct 06, 2012 at 06:43:50PM +0700, Nguyen Thai Ngoc Duy wrote:

> On Sat, Oct 6, 2012 at 6:33 PM, Philip Oakley <philipoakley@iee.org> wrote:
> >> Asciidoc 8.2.6 does not like me writing
> >> "Put \# if you need a literal #.." so I go with "backslash" and
> >> "hash" instead. `\!` displays fine both in man page and html format.
> >> '!' changed to `!` because it looks clearer in monospace.
> >
> >
> > Why not put the backslash-hash in back quotes as well to give the same
> > look/feel consistency?
> 
> Because asciidoc does not like \#, '\#' nor `\#`. It just shows \
> without # and I don't want to master asciidoc just to make it show \#.

It works fine for me with asciidoc 8.6.7. <sigh>

I would think the "inline literal" syntax started in 8.2.5 would take
care of it; maybe there were some bug fixes, considering how new it was
in your version.

I also think switching "!" to `!` is a slight regression; it will change
fonts in the HTML version, but usually not in the manpage, and the loss
of the quotes makes things harder to read. I would use both, and it does
not hurt to also spell out the name of the punctuation.

So this:

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 96639e0..c0a5851 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -73,12 +73,15 @@ PATTERN FORMAT
  - A blank line matches no files, so it can serve as a separator
    for readability.
 
- - A line starting with # serves as a comment.
+ - A line starting with "`#`" serves as a comment.
+   Put a backslash ("`\`") in front of the first hash for the patterns
+   that start with a hash (i.e., "`\#`").
 
- - An optional prefix '!' which negates the pattern; any
+ - An optional prefix "`!`" which negates the pattern; any
    matching file excluded by a previous pattern will become
    included again.  If a negated pattern matches, this will
-   override lower precedence patterns sources.
+   override lower precedence patterns sources. Use "`\!`" if
+   you need a literal "`!`" at the beginning of the pattern.
 
  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find

renders to:

       ·   A line starting with "#" serves as a comment. Put a
           backslash ("\") in front of the first hash for the patterns
           that start with a hash (i.e., "\#").

       ·   An optional prefix "!" which negates the pattern; any
           matching file excluded by a previous pattern will become
           included again. If a negated pattern matches, this will
           override lower precedence patterns sources. Use "\!" if you
           need a literal "!" at the beginning of the pattern.

-Peff

[PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Nguyễn Thái Ngọc Duy]

We support backslash escape, but we hide the details behind the phrase
"a shell glob suitable for consumption by fnmatch(3)". So it may not
be obvious how one can get literal # or ! at the beginning of pattern.
Add a few lines on how to work around the magic characters.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 On Sat, Oct 6, 2012 at 8:21 PM, Jeff King <peff@peff.net> wrote:
 > It works fine for me with asciidoc 8.6.7. <sigh>

 8.6.5 works. I don't care deeply as I read .txt anyway. Here it goes
 again with examples.

 Documentation/gitignore.txt | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 96639e0..0bcf079 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -73,12 +73,16 @@ PATTERN FORMAT
  - A blank line matches no files, so it can serve as a separator
    for readability.
 
- - A line starting with # serves as a comment.
+ - A line starting with "`#`" serves as a comment.
+   Use "`\#`" instead for patterns that begin with "`#`",
+   for example, "`\#backup#.txt`".
 
- - An optional prefix '!' which negates the pattern; any
+ - An optional prefix "`!`" which negates the pattern; any
    matching file excluded by a previous pattern will become
    included again.  If a negated pattern matches, this will
    override lower precedence patterns sources.
+   Use "`\!`" instead for patterns that begin with "`!`",
+   for example, "`\!important!.txt`".
 
  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find
-- 
1.7.12.1.406.g6ab07c4

Re: [PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Jeff King]

On Sat, Oct 06, 2012 at 08:51:24PM +0700, Nguyen Thai Ngoc Duy wrote:

> We support backslash escape, but we hide the details behind the phrase
> "a shell glob suitable for consumption by fnmatch(3)". So it may not
> be obvious how one can get literal # or ! at the beginning of pattern.
> Add a few lines on how to work around the magic characters.
> 
> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
> ---
>  On Sat, Oct 6, 2012 at 8:21 PM, Jeff King <peff@peff.net> wrote:
>  > It works fine for me with asciidoc 8.6.7. <sigh>
> 
>  8.6.5 works. I don't care deeply as I read .txt anyway. Here it goes
>  again with examples.

I'd be slightly worried that we are hurting other people who do care and
are on older versions of asciidoc. It would be nice if we actually knew
the cause of the different behaviors we saw and if there was a way to
work around it (it might not even be old asciidoc, but rather old
docbook).

Part of me wants to just take the change and see if anybody complains.
But that is probably the wrong thing to do, and just my general
frustration with our doc toolchain talking.

-Peff

Re: [PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I'd be slightly worried that we are hurting other people who do care and
> are on older versions of asciidoc. It would be nice if we actually knew
> the cause of the different behaviors we saw and if there was a way to
> work around it (it might not even be old asciidoc, but rather old
> docbook).
>
> Part of me wants to just take the change and see if anybody complains.
> But that is probably the wrong thing to do, and just my general
> frustration with our doc toolchain talking.

Yeah, I do not think we would want to introduce such a regression
especially when the proposed update is not the only (or best) way to
give us the intended benefit.  I think the "spell the character name
out" approach you showed in the other message was far more readable
anyway.

Thanks.

[PATCH v3] gitignore.txt: suggestions how to get literal # or ! at the beginning

[Nguyễn Thái Ngọc Duy]

We support backslash escape, but we hide the details behind the phrase
"a shell glob suitable for consumption by fnmatch(3)". So it may not
be obvious how one can get literal # or ! at the beginning of pattern.
Add a few lines on how to work around the magic characters.

Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
---
 Back to spelling out, which works with 8.2.6. No examples for \#
 because '\' in '\#example#.txt' is eaten.

 Documentation/gitignore.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 96639e0..90106c4 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -74,11 +74,15 @@ PATTERN FORMAT
    for readability.
 
  - A line starting with # serves as a comment.
+   Put a backslash ("`\`") in front of the first hash for patterns
+   that begin with a hash.
 
- - An optional prefix '!' which negates the pattern; any
+ - An optional prefix "`!`" which negates the pattern; any
    matching file excluded by a previous pattern will become
    included again.  If a negated pattern matches, this will
    override lower precedence patterns sources.
+   Put a backslash ("`\`") in front of the first "`!`" for patterns
+   that begin with a literal "`!`", for example, "`\!important!.txt`".
 
  - If the pattern ends with a slash, it is removed for the
    purpose of the following description, but it would only find
-- 
1.7.12.1.406.g6ab07c4