Hi,
Martin Ågren wrote:
> On Sun, 17 Mar 2019 at 20:44, Todd Zullinger <tmz@xxxxxxxxx> 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 --. 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 "+". 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
