git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning
@ 2012-10-06  8:38 Nguyễn Thái Ngọc Duy
  2012-10-06 11:33 ` Philip Oakley
  0 siblings, 1 reply; 8+ messages in thread
From: Nguyễn Thái Ngọc Duy @ 2012-10-06  8:38 UTC (permalink / raw)
  To: git; +Cc: Junio C Hamano, 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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06  8:38 [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning Nguyễn Thái Ngọc Duy
@ 2012-10-06 11:33 ` Philip Oakley
  2012-10-06 11:43   ` Nguyen Thai Ngoc Duy
  0 siblings, 1 reply; 8+ messages in thread
From: Philip Oakley @ 2012-10-06 11:33 UTC (permalink / raw)
  To: Nguyễn Thái Ngọc Duy, git; +Cc: Junio C Hamano

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 11:33 ` Philip Oakley
@ 2012-10-06 11:43   ` Nguyen Thai Ngoc Duy
  2012-10-06 13:21     ` Jeff King
  0 siblings, 1 reply; 8+ messages in thread
From: Nguyen Thai Ngoc Duy @ 2012-10-06 11:43 UTC (permalink / raw)
  To: Philip Oakley; +Cc: git, Junio C Hamano

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 11:43   ` Nguyen Thai Ngoc Duy
@ 2012-10-06 13:21     ` Jeff King
  2012-10-06 13:51       ` [PATCH v2] " Nguyễn Thái Ngọc Duy
  0 siblings, 1 reply; 8+ messages in thread
From: Jeff King @ 2012-10-06 13:21 UTC (permalink / raw)
  To: Nguyen Thai Ngoc Duy; +Cc: Philip Oakley, git, Junio C Hamano

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 13:21     ` Jeff King
@ 2012-10-06 13:51       ` Nguyễn Thái Ngọc Duy
  2012-10-06 15:40         ` Jeff King
  0 siblings, 1 reply; 8+ messages in thread
From: Nguyễn Thái Ngọc Duy @ 2012-10-06 13:51 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Jeff King, Philip Oakley,
	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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 13:51       ` [PATCH v2] " Nguyễn Thái Ngọc Duy
@ 2012-10-06 15:40         ` Jeff King
  2012-10-06 18:25           ` Junio C Hamano
  0 siblings, 1 reply; 8+ messages in thread
From: Jeff King @ 2012-10-06 15:40 UTC (permalink / raw)
  To: Nguyễn Thái Ngọc Duy; +Cc: git, Junio C Hamano, Philip Oakley

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

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH v2] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 15:40         ` Jeff King
@ 2012-10-06 18:25           ` Junio C Hamano
  2012-10-07  3:13             ` [PATCH v3] " Nguyễn Thái Ngọc Duy
  0 siblings, 1 reply; 8+ messages in thread
From: Junio C Hamano @ 2012-10-06 18:25 UTC (permalink / raw)
  To: Jeff King; +Cc: Nguyễn Thái Ngọc Duy, git, Philip Oakley

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.

^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH v3] gitignore.txt: suggestions how to get literal # or ! at the beginning
  2012-10-06 18:25           ` Junio C Hamano
@ 2012-10-07  3:13             ` Nguyễn Thái Ngọc Duy
  0 siblings, 0 replies; 8+ messages in thread
From: Nguyễn Thái Ngọc Duy @ 2012-10-07  3:13 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Jeff King, Philip Oakley,
	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

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2012-10-07  3:21 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2012-10-06  8:38 [PATCH] gitignore.txt: suggestions how to get literal # or ! at the beginning Nguyễn Thái Ngọc Duy
2012-10-06 11:33 ` Philip Oakley
2012-10-06 11:43   ` Nguyen Thai Ngoc Duy
2012-10-06 13:21     ` Jeff King
2012-10-06 13:51       ` [PATCH v2] " Nguyễn Thái Ngọc Duy
2012-10-06 15:40         ` Jeff King
2012-10-06 18:25           ` Junio C Hamano
2012-10-07  3:13             ` [PATCH v3] " Nguyễn Thái Ngọc Duy

Code repositories for project(s) associated with this 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).