discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Steffen Nurpmeso <sdaoden@yandex.com>
Cc: discuss@mdocml.bsd.lv
Subject: Re: Mdocdate
Date: Sun, 15 Nov 2015 02:51:43 +0100	[thread overview]
Message-ID: <20151115015143.GG22003@athene.usta.de> (raw)
In-Reply-To: <20151114150201.btVpSjagp%sdaoden@yandex.com>

Hi Steffen,

Steffen Nurpmeso wrote on Sat, Nov 14, 2015 at 04:02:01PM +0100:
> Ingo Schwarze <schwarze@usta.de> wrote:

>> generate non-portable output.  Actually, it might be possible with
>> a bit of effort to get similar patches into groff and Heirloom,
>> Werner and Carsten are usually very helpful - but i'm not convinced
>> the format you propose makes much sense.  We really don't need
>> seconds and timezones in .Dd, and i wouldn't know how to explain
>> the need to Werner and Carsten.  Rather than trying to change the
>> world, i think it makes more sense to teach SVN to generate .Dd
 
> but i think ISO 8601 / RFC 3339 "full-date" would be a useful
> extension since they are (a) standardized and well-known

As a whole, ISO 8601 provides *much* too many options.
Allowing many different formats only confuses authors,
endangers portability, and provides a fertile ground for bugs.

A manual page language should encourage *one* simple, uniform
format.  That is fully sufficient for the purpose, easiest to
implement, easiest to document, and easiest to remember for
authors.

Actually, we are almost there.  For the legacy man(7) language, the
traditional format used is YYYY-MM-DD.  For the mdoc(7) language,
the only format fully supported has always been "Month [D]D, YYYY".
It's not ideal that both are different, but man(7) is slowly dying
anyway, so things settle on "Month [D]D, YYYY".

> and (b) locale / charset agnostic and worldwide relatively (it
> is a Gregorian date in the end) easy perceivable.
>
> I lack the overview, but localized manpages have to ship with
> those english / american dates, too?

Yes.

Of course, if you translate a manual page, you can choose to provide
a .Dd argument in chinese letters using a chinese calendar.  But
you should understand the consequences:  All formatters except
mandoc(1) will ignore your chinese date, show the date of *formatting*
of the manual instead, using english conventions.  Mandoc will warn
that the date is invalid and non-portable and will show it verbatim.

Besides, portability of translated manuals is poor anyway.
For example, you cannot translate the "SYNOPSIS" section header
without breaking important functionality.  A very ugly workaround
exists (.nr nS) that works with groff and mandoc, but isn't
portable to any other formatters.  There are lots and lots of
similar gotchas all over the place that are more important
than the date format.

You should also be aware that there is almost no interest in
translated documentation.  I have talked to Japanese people multiple
times, and they invariably said:  "Yes, now and then somebody
translates a few pages, but then they get outdated soon and are
abondoned.  Nobody really uses translated documentation.  People
really value that using the authoritative english versions, you can
be sure that what you read is true."  What russian people told me
hardly sounded different.  And those - Japan and Russia - are two
countries where speaking english is somewhat less common than in
western and central Europe.  I have yet to meet french or german
people who feel that french or german manuals would be useful.

Don't get me wrong:  If somebody wants to translate a manual, i
don't want the tools to hinder them.  That's why we support UTF-8
output for a long time and have improved UTF-8 input recently.
That's why i regularly ask people at conferences whether they are
aware of any issues with non-english documentation.  Such conversation
rarely reveal any issues, and in the few cases where they do, they
can often be fixed without collecting technical debt in the code.

But it is very important to not weaken the language definition for
the sake of straw-man internationalization arguments.  It is not
even possible to properly *design* comprehensive internationalization
interfaces simply because demand is so elusive.  Unless some new
code is put to intensive use right away, the design will inevitably
become a bad design-by-committee one.  That will only hurt everyone.

> So no, now that groff's mdoc
> has been extended to support mdocml's cvs(1) tag natively i think
> i'll add ISO 8601 YYYY-MM-DD to my mdoc copy once i come to
> development of my roff fork, and add a Savannah bug report with
> the patch, then.

Sounds like a bad idea.  Mdocdate support was added to groff
a decade after thousands of manuals using that convention existed
in the wild.  It was the first system ever to support autogeneration
of .Dd content.  Those are sufficiently strong reasons for adding
a new feature.

None of these reasons apply to allowing YYYY-MM-DD in .Dd.
No such manuals exist in the wild yet using that format, and it's
still time to prevent bloating the definition of this user interface.
Adding another format is not required; an established format for
autogeneration already exists.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

  reply	other threads:[~2015-11-15  1:51 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-11-12  9:25 Mdocdate Dag-Erling Smørgrav
2015-11-12 21:31 ` Mdocdate Ingo Schwarze
2015-11-12 23:06   ` Mdocdate Ingo Schwarze
2015-11-13  5:52   ` Mdocdate Dag-Erling Smørgrav
2015-11-14  1:22     ` Mdocdate Ingo Schwarze
2015-11-14 15:02       ` Mdocdate Steffen Nurpmeso
2015-11-15  1:51         ` Ingo Schwarze [this message]
2015-11-16 13:35           ` Mdocdate Steffen Nurpmeso
2015-11-17  9:12             ` Mdocdate Svyatoslav Mishyn
2015-11-17 10:35               ` Mdocdate Steffen Nurpmeso
2015-11-23 20:48   ` Mdocdate Michael Dexter

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=20151115015143.GG22003@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mdocml.bsd.lv \
    --cc=sdaoden@yandex.com \
    --subject='Re: Mdocdate' \
    /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

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).