Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

[Todd Zullinger <tmz@pobox.com>]

Hi,

Martin Ågren wrote:
> On Sun, 17 Mar 2019 at 20:44, Todd Zullinger <tmz@pobox.com> wrote:
>> Martin Ågren wrote:
>> +ASCIIDOC_EXTRA += -a mansource="Git $(GIT_VERSION)" -a manmanual="Git Manual"
> 
> So to be honest, I still don't understand how this works, but it does,
> great. I really need to improve my documentation-reading skills.

Let me know if you find any good methods for perfect
retention.  I've re-read enough documentation for a
lifetime. ;)

> I had some more time to look at this. Thanks for getting started on this
> switch. A few things I noticed:
> 
> {litdd} now renders as &#x2d;&#x2d. We should find some other way to
> produce '--'. This should then be a simple change, as we're already
> providing this attribute inside an `ifdef USE_ASCIIDOCTOR`.

I noticed that one and didn't work out a good fix, but it
sounds like you have one in mind.  That's great.

> "+" becomes "&#43;". I didn't immediately find where we do that.

For this one, I was working on replacing "{plus}" with `+`
(along with " " and "-").  That's probably not ideal though.

This is what I had to test:

-- 8< --
Subject: [PATCH] WIP: wrap "[ +-]" in backticks (NOT FOR SUBMISSION)

asciidoctor's manpage output html-encodes "{plus}" which seems like a
bug.  At the least it needs some option I've yet to learn.
---
 Documentation/git-add.txt | 26 +++++++++++++-------------
 Documentation/gitweb.txt  |  6 +++---
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 37bcab94d5..dc1dd3a91b 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -363,20 +363,20 @@ may see in a patch, and which editing operations make sense on them.
 --
 added content::
 
-Added content is represented by lines beginning with "{plus}". You can
+Added content is represented by lines beginning with `"+"`. You can
 prevent staging any addition lines by deleting them.
 
 removed content::
 
-Removed content is represented by lines beginning with "-". You can
-prevent staging their removal by converting the "-" to a " " (space).
+Removed content is represented by lines beginning with `"-"`. You can
+prevent staging their removal by converting the `"-"` to a `" "` (space).
 
 modified content::
 
-Modified content is represented by "-" lines (removing the old content)
-followed by "{plus}" lines (adding the replacement content). You can
-prevent staging the modification by converting "-" lines to " ", and
-removing "{plus}" lines. Beware that modifying only half of the pair is
+Modified content is represented by `"-"` lines (removing the old content)
+followed by `"+"` lines (adding the replacement content). You can
+prevent staging the modification by converting `"-"` lines to `" "`, and
+removing `"+"` lines. Beware that modifying only half of the pair is
 likely to introduce confusing changes to the index.
 --
 
@@ -393,29 +393,29 @@ Avoid using these constructs, or do so with extreme caution.
 removing untouched content::
 
 Content which does not differ between the index and working tree may be
-shown on context lines, beginning with a " " (space).  You can stage
-context lines for removal by converting the space to a "-". The
+shown on context lines, beginning with a `" "` (space).  You can stage
+context lines for removal by converting the space to a `"-"`. The
 resulting working tree file will appear to re-add the content.
 
 modifying existing content::
 
 One can also modify context lines by staging them for removal (by
-converting " " to "-") and adding a "{plus}" line with the new content.
-Similarly, one can modify "{plus}" lines for existing additions or
+converting `" "` to `"-"`) and adding a `"+"` line with the new content.
+Similarly, one can modify `"+"` lines for existing additions or
 modifications. In all cases, the new modification will appear reverted
 in the working tree.
 
 new content::
 
 You may also add new content that does not exist in the patch; simply
-add new lines, each starting with "{plus}". The addition will appear
+add new lines, each starting with `"+"`. The addition will appear
 reverted in the working tree.
 --
 
 There are also several operations which should be avoided entirely, as
 they will make the patch impossible to apply:
 
-* adding context (" ") or removal ("-") lines
+* adding context (`" "`) or removal (`"-"`) lines
 * deleting context or removal lines
 * modifying the contents of context or removal lines
 
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
index 88450589af..d27f239242 100644
--- a/Documentation/gitweb.txt
+++ b/Documentation/gitweb.txt
@@ -80,15 +80,15 @@ continuation (newline escaping).
 * Leading and trailing whitespace are ignored.
 
 * Whitespace separated fields; any run of whitespace can be used as field
-separator (rules for Perl's "`split(" ", $line)`").
+separator (rules for Perl's "`split(`" "`, $line)`").
 
 * Fields use modified URI encoding, defined in RFC 3986, section 2.1
 (Percent-Encoding), or rather "Query string encoding" (see
 https://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
-being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be
+being that SP (`" "`) can be encoded as `"+"` (and therefore `"+"` has to be
 also percent-encoded).
 +
-Reserved characters are: "%" (used for encoding), "{plus}" (can be used to
+Reserved characters are: "%" (used for encoding), `"+"` (can be used to
 encode SPACE), all whitespace characters as defined in Perl, including SP,
 TAB and LF, (used to separate fields in a record).

-- 8< --

> `./doc-diff HEAD^ HEAD` shows how several "git-\nfoo" become
> "\ngit-foo", i.e., linkgit expansions are now treated as non-breaking.
> That's arguably good, but it brings some noise to the diff. Maybe one
> should try and see if it's possible to break that to have a nicer
> diff, then remove that breakage in a follow-up commit. Or, if it's
> possible to make "git-foo" non-breaking before the switch. Hmm, was this
> why you increased MANWIDTH?

Yeah, I noticed a number of places where asciidoc and
asciidoctor wrapped lines at slightly different places.  I
didn't see if they were all due to wrapping at a dashed git
command, but that could certainly have been the main cause.

I set the large MANWIDTH and then I think I added
--color-words to the diff call in doc-diff.

> A double-space between sentences turns into a single space -- at least
> in constructions such as "... to foobar. `git-foo` does ...". Not a
> problem perhaps, but noise in the diff.
> 
> And I'm sure there's more lurking in that huge diff. Whether any of that
> is significant or not is another matter. ;-)

Oh my yes, I'm sure. :)

-- 
Todd