Re: [PATCH v4 4/6] doc: use modern "`"-style code fencing

[Jeff King]

On Mon, Oct 02, 2017 at 10:35:45AM +0900, Junio C Hamano wrote:

> Taylor Blau  writes:
> 
> >> Is this just me who wants to do s/fenc/quot/g?  Unless somebody
> >> objects, I'd do so while queuing.
> >
> > I don't object, I think that fencing is less appropriate than quoting.
> > I couldn't find the term myself when writing this commit :-).
> >
> > I am happy to send out v5 of this patch series with this commit
> > re-written, or you can change it while queuing. Whichever is easier for
> > you.
> 
> Just FYI, here is what I ended up with.  I do not think this is
> about "modern" vs "old style"; it is more about using the more
> appropriate mark-up and our desire has always been to use `literal`
> for things that users need to type literally.

I think it was my earlier comment that led to the modern/old notion. A
lot of the old code does use single-quotes haphazardly. I'm not sure if
it's "old style" or just "we were less careful" then. Either way, the
patch looks good to me.

I also think fencing isn't the right word; that word implies to me a
multi-line block like

---
this is fenced
---

-Peff

Re: [PATCH v4 4/6] doc: use modern "`"-style code fencing

[Junio C Hamano]

Taylor Blau  writes:

>> Is this just me who wants to do s/fenc/quot/g?  Unless somebody
>> objects, I'd do so while queuing.
>
> I don't object, I think that fencing is less appropriate than quoting.
> I couldn't find the term myself when writing this commit :-).
>
> I am happy to send out v5 of this patch series with this commit
> re-written, or you can change it while queuing. Whichever is easier for
> you.

Just FYI, here is what I ended up with.  I do not think this is
about "modern" vs "old style"; it is more about using the more
appropriate mark-up and our desire has always been to use `literal`
for things that users need to type literally.

I notice that I didn't remove 'modern' from the title in the versoin
below, though.

Thanks.

commit a184d836bcf1a557520095a90b22edf659ee88f2
Author: Taylor Blau 
Date:   Sun Oct 1 09:18:50 2017 -0700

doc: use modern "``"-style quoting for literal strings

"''"-style quoting is not appropriate when quoting literal
strings in the "Documentation/" subtree.

In preparation for adding additional information to this section of
git-for-each-ref(1)'s documentation, update them to use "``"
instead.

Signed-off-by: Taylor Blau 
Signed-off-by: Junio C Hamano 

Re: [PATCH v4 4/6] doc: use modern "`"-style code fencing

[Taylor Blau]

On Mon, Oct 02, 2017 at 08:55:53AM +0900, Junio C Hamano wrote:
> Taylor Blau  writes:
>
> > "'"- (single-quote) styled code fencing is no longer considered modern
> > within the "Documentation/" subtree.
> >
> > In preparation for adding additional information to this section of
> > git-for-each-ref(1)'s documentation, update old-style code fencing to
> > use "`"-style fencing instead.
>
> Is this just me who wants to do s/fenc/quot/g?  Unless somebody
> objects, I'd do so while queuing.

I don't object, I think that fencing is less appropriate than quoting.
I couldn't find the term myself when writing this commit :-).

I am happy to send out v5 of this patch series with this commit
re-written, or you can change it while queuing. Whichever is easier for
you.

Thanks again.


--
- Taylor

Re: [PATCH v4 4/6] doc: use modern "`"-style code fencing

[Junio C Hamano]

Taylor Blau  writes:

> "'"- (single-quote) styled code fencing is no longer considered modern
> within the "Documentation/" subtree.
>
> In preparation for adding additional information to this section of
> git-for-each-ref(1)'s documentation, update old-style code fencing to
> use "`"-style fencing instead.

Is this just me who wants to do s/fenc/quot/g?  Unless somebody
objects, I'd do so while queuing.

Thanks.

>
> Signed-off-by: Taylor Blau 
> ---
>  Documentation/git-for-each-ref.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-for-each-ref.txt 
> b/Documentation/git-for-each-ref.txt
> index 323ce07de..1279b9733 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -213,12 +213,12 @@ and `date` to extract the named component.
>  The complete message in a commit and tag object is `contents`.
>  Its first line is `contents:subject`, where subject is the concatenation
>  of all lines of the commit message up to the first blank line.  The next
> -line is 'contents:body', where body is all of the lines after the first
> +line is `contents:body`, where body is all of the lines after the first
>  blank line.  The optional GPG signature is `contents:signature`.  The
>  first `N` lines of the message is obtained using `contents:lines=N`.
>  Additionally, the trailers as interpreted by 
> linkgit:git-interpret-trailers[1]
> -are obtained as 'trailers' (or by using the historical alias
> -'contents:trailers').
> +are obtained as `trailers` (or by using the historical alias
> +`contents:trailers`).
>  
>  For sorting purposes, fields with numeric values sort in numeric order
>  (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).

[PATCH v4 4/6] doc: use modern "`"-style code fencing

[Taylor Blau]

"'"- (single-quote) styled code fencing is no longer considered modern
within the "Documentation/" subtree.

In preparation for adding additional information to this section of
git-for-each-ref(1)'s documentation, update old-style code fencing to
use "`"-style fencing instead.

Signed-off-by: Taylor Blau 
---
 Documentation/git-for-each-ref.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-for-each-ref.txt 
b/Documentation/git-for-each-ref.txt
index 323ce07de..1279b9733 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -213,12 +213,12 @@ and `date` to extract the named component.
 The complete message in a commit and tag object is `contents`.
 Its first line is `contents:subject`, where subject is the concatenation
 of all lines of the commit message up to the first blank line.  The next
-line is 'contents:body', where body is all of the lines after the first
+line is `contents:body`, where body is all of the lines after the first
 blank line.  The optional GPG signature is `contents:signature`.  The
 first `N` lines of the message is obtained using `contents:lines=N`.
 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
-are obtained as 'trailers' (or by using the historical alias
-'contents:trailers').
+are obtained as `trailers` (or by using the historical alias
+`contents:trailers`).
 
 For sorting purposes, fields with numeric values sort in numeric order
 (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
-- 
2.14.1.145.gb3622a4ee