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

From: Jeff King <peff@peff.net>
Date: Oct 6, 2012, 13:21 UTC
Message-ID: <20121006132127.GC11712@sigill.intra.peff.net>
In-Reply-To: <CACsJy8DObOJUSdDPEsTwAKjXMYiOyf7P_6oEE9xbU6QFz7rOxQ@mail.gmail.com>

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

Show 12 quoted lines

> 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