From: Todd Zullinger <tmz@pobox.com>
To: "Martin Ågren" <martin.agren@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>,
"brian m. carlson" <sandals@crustytoothpaste.net>,
Jeff King <peff@peff.net>
Subject: Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`
Date: Wed, 20 Mar 2019 14:17:15 -0400 [thread overview]
Message-ID: <20190320181715.GJ31362@pobox.com> (raw)
In-Reply-To: <CAN0heSrajiswzpm+au_5nmZMZG9406iZa-CK9p5CaHLTuxm8nw@mail.gmail.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 --. 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
next prev parent reply other threads:[~2019-03-20 18:17 UTC|newest]
Thread overview: 71+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-17 14:47 [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-03-17 19:44 ` Todd Zullinger
2019-03-17 20:03 ` Martin Ågren
2019-03-19 7:02 ` Martin Ågren
2019-03-20 18:17 ` Todd Zullinger [this message]
2019-03-22 21:01 ` Martin Ågren
2019-03-23 19:27 ` Todd Zullinger
2019-03-24 12:16 ` Jeff King
2019-03-24 16:21 ` Todd Zullinger
2019-03-25 15:06 ` Jeff King
2019-03-25 19:00 ` Todd Zullinger
2019-03-27 1:06 ` Todd Zullinger
2019-03-27 10:05 ` SZEDER Gábor
2019-03-28 0:06 ` brian m. carlson
2019-03-30 18:00 ` Todd Zullinger
2019-03-30 21:04 ` brian m. carlson
2019-04-05 2:17 ` Todd Zullinger
2019-04-05 18:46 ` Jeff King
2019-03-28 2:54 ` Jeff King
2019-03-28 3:33 ` Jeff King
2019-03-19 2:46 ` Jeff King
2019-03-19 2:59 ` Jeff King
2019-03-19 3:55 ` Junio C Hamano
2019-03-19 7:33 ` Martin Ågren
2019-03-19 7:36 ` Martin Ågren
2019-09-03 18:51 ` [PATCH v2 0/2] " Martin Ågren
2019-09-03 18:51 ` [PATCH v2 1/2] " Martin Ågren
2019-09-03 18:51 ` [PATCH v2 2/2] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-09-03 23:16 ` [PATCH v2 0/2] asciidoctor-extensions: provide `<refmiscinfo/>` brian m. carlson
2019-09-05 19:28 ` Martin Ågren
2019-09-04 3:26 ` Jeff King
2019-09-05 19:35 ` Martin Ågren
2019-09-07 6:45 ` Jeff King
2019-09-07 14:06 ` Martin Ågren
2019-09-08 21:30 ` Jeff King
2019-09-06 23:29 ` brian m. carlson
2019-09-07 4:40 ` Jeff King
2019-09-07 16:53 ` brian m. carlson
2019-09-07 17:07 ` [PATCH] Documentation: fix build with Asciidoctor 2 brian m. carlson
2019-09-08 10:48 ` Jeff King
2019-09-08 17:18 ` brian m. carlson
2019-09-08 21:21 ` Jeff King
2019-09-08 22:24 ` brian m. carlson
2019-09-09 17:37 ` Junio C Hamano
2019-09-10 18:44 ` Jeff King
2019-09-11 23:19 ` brian m. carlson
2019-09-08 14:13 ` SZEDER Gábor
2019-09-08 21:32 ` Jeff King
2019-09-13 1:52 ` [PATCH v2] " brian m. carlson
2019-09-13 5:06 ` Jeff King
2019-09-13 17:06 ` Junio C Hamano
2019-09-16 10:47 ` Martin Ågren
2019-09-16 17:43 ` Junio C Hamano
2019-09-14 7:53 ` SZEDER Gábor
2019-09-14 19:44 ` brian m. carlson
2019-09-14 19:49 ` [PATCH v3] " brian m. carlson
2019-09-15 9:59 ` SZEDER Gábor
2019-09-15 21:26 ` brian m. carlson
2019-09-15 22:05 ` SZEDER Gábor
2019-09-15 22:14 ` brian m. carlson
2019-09-16 10:51 ` Martin Ågren
2019-09-15 22:43 ` [PATCH v4] " brian m. carlson
2019-09-16 19:00 ` [PATCH v3 0/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00 ` [PATCH v3 1/3] Doc/Makefile: give mansource/-version/-manual attributes Martin Ågren
2019-09-16 19:00 ` [PATCH v3 2/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00 ` [PATCH v3 3/3] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-03-19 3:30 ` [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Jeff King
2019-03-19 7:12 ` Martin Ågren
2019-03-19 7:43 ` Jeff King
2019-03-20 18:32 ` Todd Zullinger
2019-03-19 7:10 ` Martin Ågren
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190320181715.GJ31362@pobox.com \
--to=tmz@pobox.com \
--cc=git@vger.kernel.org \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
--cc=sandals@crustytoothpaste.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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 NNTP newsgroup(s).