Re: [PATCH 2/4] Emphasize options and force ASCIIDOC escaping of --

2013-11-12 Thread Jeff King
On Fri, Nov 08, 2013 at 07:48:51PM -0500, Jason St. John wrote:

  Using more options generally further limits the output (e.g.
 -`--since=date1` limits to commits newer than `date1`, and using it
 -with `--grep=pattern` further limits to commits whose log message
 +'\--since=date1' limits to commits newer than `date1`, and using it
 +with '\--grep=pattern' further limits to commits whose log message
  has a line that matches `pattern`), unless otherwise noted.

Others pointed out that we generally prefer the `literal` formatting for
such options (with backticks), which I agree with. If your target is
formatting manpages (and not html), you may want to build with
MAN_BOLD_LITERAL set in the Makefile, which will embolden the literals
in the output (since we cannot typeset them in a monospace font on the
terminal, as we would for html).

-Peff
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html


Re: [PATCH 2/4] Emphasize options and force ASCIIDOC escaping of --

2013-11-11 Thread Junio C Hamano
Jason St. John jstj...@purdue.edu writes:

 rev-list-options.txt: replace e.g. `--foo` with '\--foo'
 rev-list-options.txt: emphasize, instead of quote, some option arguments
 (e.g. foo-option becomes 'foo-option')
 rev-list-options.txt: force ASCIIDOC escaping of -- (e.g. '--bar'
 becomes '\--bar')
 rev-list-options.txt: add single quote chars around options missing them
 (e.g. --grep becomes '\--grep')
 rev-list-options.txt: replaced one instance of regexp with regular
 expressions
 rev-list-options.txt: fix typo in --no-walk description (show --
 shown)
 rev-list-options.txt: replaced some instances of double quotes with
 their ASCIIDOC equivalent (e.g. a - character becomes
 a ``-'' character,

Gaah.

Did you really have to repeat rev-list-options.txt:  on all the
lines?

 Sorry for the messy quoting in the last set of examples in the commit message.

I have a feeling that many of them can and should be turned from
'--opt' to `--opt`.  For example, this original:

   Mark which side of a symmetric diff a commit is reachable from.
   Commits from the left side are prefixed with `` and those from
 - the right with ``.  If combined with `--boundary`, those
 - commits are prefixed with `-`.
 + the right with ``.  If combined with '\--boundary', those
 + commits are prefixed with ``-''.

seems to render correctly at

https://git-htmldocs.googlecode.com/git/git-rev-list.html

without this part of the patch.

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html


Re: [PATCH 2/4] Emphasize options and force ASCIIDOC escaping of --

2013-11-09 Thread Johannes Sixt
Am 09.11.2013 01:48, schrieb Jason St. John:
 -`--since=date1` limits to commits newer than `date1`, and using it
 -with `--grep=pattern` further limits to commits whose log message
 +'\--since=date1' limits to commits newer than `date1`, and using it
 +with '\--grep=pattern' further limits to commits whose log message

I don't think this kind of change goes in the right direction.
Currently, the general style seems to be that options are typeset in
monospaced font. I looked at git-merge and git-rebase (and git-log, of
course). But after your change, they are typeset in italics, in the HTML
version of the manual pages.

I did not find an advice on the preferred formatting, though, except for
the last sentence in Documentation/CodingGuidelines.

-- Hannes

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[PATCH 2/4] Emphasize options and force ASCIIDOC escaping of --

2013-11-08 Thread Jason St. John
rev-list-options.txt: replace e.g. `--foo` with '\--foo'
rev-list-options.txt: emphasize, instead of quote, some option arguments
(e.g. foo-option becomes 'foo-option')
rev-list-options.txt: force ASCIIDOC escaping of -- (e.g. '--bar'
becomes '\--bar')
rev-list-options.txt: add single quote chars around options missing them
(e.g. --grep becomes '\--grep')
rev-list-options.txt: replaced one instance of regexp with regular
expressions
rev-list-options.txt: fix typo in --no-walk description (show --
shown)
rev-list-options.txt: replaced some instances of double quotes with
their ASCIIDOC equivalent (e.g. a - character becomes
a ``-'' character,

Signed-off-by: Jason St. John jstj...@purdue.edu
---
Sorry for the messy quoting in the last set of examples in the commit message.
There wasn't really any way to work around it other than omitting the quotes
around the before and after parts, which I didn't want to do.


 Documentation/rev-list-options.txt | 136 ++---
 1 file changed, 68 insertions(+), 68 deletions(-)

diff --git a/Documentation/rev-list-options.txt 
b/Documentation/rev-list-options.txt
index 5bdfb42..32c40ae 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -6,12 +6,12 @@ special notations explained in the description, additional 
commit
 limiting may be applied.
 
 Using more options generally further limits the output (e.g.
-`--since=date1` limits to commits newer than `date1`, and using it
-with `--grep=pattern` further limits to commits whose log message
+'\--since=date1' limits to commits newer than `date1`, and using it
+with '\--grep=pattern' further limits to commits whose log message
 has a line that matches `pattern`), unless otherwise noted.
 
 Note that these are applied before commit
-ordering and formatting options, such as `--reverse`.
+ordering and formatting options, such as '\--reverse'.
 
 --
 
@@ -47,31 +47,31 @@ endif::git-rev-list[]
 
Limit the commits output to ones with author/committer
header lines that match the specified pattern (regular
-   expression).  With more than one `--author=pattern`,
+   expression).  With more than one '\--author=pattern',
commits whose author matches any of the given patterns are
-   chosen (similarly for multiple `--committer=pattern`).
+   chosen (similarly for multiple '\--committer=pattern').
 
 --grep-reflog=pattern::
 
Limit the commits output to ones with reflog entries that
match the specified pattern (regular expression). With
-   more than one `--grep-reflog`, commits whose reflog message
+   more than one '\--grep-reflog', commits whose reflog message
matches any of the given patterns are chosen.  It is an
-   error to use this option unless `--walk-reflogs` is in use.
+   error to use this option unless '\--walk-reflogs' is in use.
 
 --grep=pattern::
 
Limit the commits output to ones with log message that
matches the specified pattern (regular expression).  With
-   more than one `--grep=pattern`, commits whose message
+   more than one '\--grep=pattern', commits whose message
matches any of the given patterns are chosen (but see
-   `--all-match`).
+   '\--all-match').
 +
-When `--show-notes` is in effect, the message from the notes as
+When '\--show-notes' is in effect, the message from the notes as
 if it is part of the log message.
 
 --all-match::
-   Limit the commits output to ones that match all given --grep,
+   Limit the commits output to ones that match all given '\--grep',
instead of ones that match at least one.
 
 -i::
@@ -98,7 +98,7 @@ if it is part of the log message.
 
 --perl-regexp::
 
-   Consider the limiting patterns to be Perl-compatible regexp.
+   Consider the limiting patterns to be Perl-compatible regular 
expressions.
Requires libpcre to be compiled in.
 
 --remove-empty::
@@ -107,12 +107,12 @@ if it is part of the log message.
 
 --merges::
 
-   Print only merge commits. This is exactly the same as `--min-parents=2`.
+   Print only merge commits. This is exactly the same as 
'\--min-parents=2'.
 
 --no-merges::
 
Do not print commits with more than one parent. This is
-   exactly the same as `--max-parents=1`.
+   exactly the same as '\--max-parents=1'.
 
 --min-parents=number::
 --max-parents=number::
@@ -120,13 +120,13 @@ if it is part of the log message.
 --no-max-parents::
 
Show only commits which have at least (or at most) that many parent
-   commits. In particular, `--max-parents=1` is the same as `--no-merges`,
-   `--min-parents=2` is the same as `--merges`.  `--max-parents=0`
-   gives all root commits and `--min-parents=3` all octopus merges.
+   commits. In particular, '\--max-parents=1' is the same as 
'\--no-merges',
+   '\--min-parents=2` is the same as '\--merges'.  '\--max-parents=0'
+