git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Martin Ågren" <martin.agren@gmail.com>
Cc: git@vger.kernel.org
Subject: Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again
Date: Fri, 14 May 2021 05:35:11 +0900	[thread overview]
Message-ID: <xmqqsg2q9xts.fsf@gitster.g> (raw)
In-Reply-To: <cover.1620928059.git.martin.agren@gmail.com> ("Martin =?utf-8?Q?=C3=85gren=22's?= message of "Thu, 13 May 2021 20:17:39 +0200")

Martin Ågren <martin.agren@gmail.com> writes:

> These patches reduce
>
>   ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD
>
> from ~1200 to ~1000 lines. It's the usual mix of things where one or the
> other of the tools renders something less well, or where we're doing
> something odd in the source and we just happen to notice it in the diff.
>
> My ulterior motive here is to have a smaller doc-diff when I post a
> patch to switch the default to Asciidoctor (with xmlto), so that it gets
> a bit easier to reason about. But if everybody gets prettier docs,
> that's also good.
>
> Some of these rephrase wording such as "other peoples' commits" to avoid
> that apostrophe at the end of a word. I'm hoping those rephrasings don't
> regress the quality of the text -- if they do, I'll be happy to try
> something else.

It is sad, but we really should try "something else", unfortunately.

I do agree with the "motive" very much---even though condensing it
down to plain text before running comparison already loses too much
information, doc-diff is the only tool we currently have to
effectively review regressions in rendered document, and the
proposed transition cannot be done safely with confidence without
being able to vet the differences.  I am happy to hear about 17%
reduction already, but the requirement to rewrite things like "other
peoples' commits" is a dealbreaker.

I am not so worried about the existing text you rewrote in these
patches.  I however do not want to see asciidoc(tor) dictating use
of a strange dialect of English when we write new documentation or
update existing ones by imposing rules like "you are not allowed to
use apostrophe-es to express possessive, and instead use 'of'"; it
will become a continuing burden for anybody who writes documentation
for us.

A typesettig rule like "instead of double-dashes --, use {litdd}" is
an acceptable way out.  At least that wouldn't constrain what the
final product that gets delivered to the end-users can say.

Thanks.

  parent reply	other threads:[~2021-05-13 20:35 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-13 18:17 Martin Ågren
2021-05-13 18:17 ` [PATCH 1/6] git-http-push.txt,git-send-pack.txt: avoid single quote Martin Ågren
2021-05-13 18:17 ` [PATCH 2/6] git-range-diff.txt: avoid single quotes Martin Ågren
2021-05-13 18:17 ` [PATCH 3/6] git-check-ref-format.txt: avoid single quote Martin Ågren
2021-05-13 19:16   ` Eric Sunshine
2021-05-13 19:35     ` Martin Ågren
2021-05-13 22:00   ` Junio C Hamano
2021-05-14  9:07     ` Martin Ågren
2021-05-14 12:30       ` Felipe Contreras
2021-05-14  5:30   ` Jeff King
2021-05-14  9:08     ` Martin Ågren
2021-05-13 18:17 ` [PATCH 4/6] diff-options.txt: move monospace markup out of attribute Martin Ågren
2021-05-13 18:17 ` [PATCH 5/6] git-svn.txt: change verse to listing block Martin Ågren
2021-05-13 18:17 ` [PATCH 6/6] Doc: use two backticks for monospace, not backtick+apostrophe Martin Ågren
2021-05-13 20:35 ` Junio C Hamano [this message]
2021-05-14  8:40   ` [PATCH 0/6] AsciiDoc vs Asciidoctor, once again Martin Ågren
2021-05-14 12:18     ` Felipe Contreras
2021-05-14  1:40 ` Felipe Contreras
2021-05-14  8:43   ` Martin Ågren
2021-05-14 12:24     ` Felipe Contreras
2021-05-14 15:28       ` Martin Ågren
2021-05-14 20:11         ` Felipe Contreras

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

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqsg2q9xts.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=martin.agren@gmail.com \
    --subject='Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again' \
    /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

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git