discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Steffen Nurpmeso <sdaoden@yandex.com>
To: Ingo Schwarze <schwarze@usta.de>
Cc: discuss@mdocml.bsd.lv
Subject: Re: Mdocdate
Date: Mon, 16 Nov 2015 14:35:44 +0100	[thread overview]
Message-ID: <20151116133544.XUCkX-64J%sdaoden@yandex.com> (raw)
In-Reply-To: <20151115015143.GG22003@athene.usta.de>

Hallo Ingo!

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

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

Yes, i think so.  I don't know for sure since the PDF costs about
120 Euro and i never was and am not interested enough to spend
that much money for the standard.  (And that is Switzerland where
refugees live in atomic bunkers and may only walk on the land some
hours a day since more than a decade at least, yet everybody knows
that a lot of weapon dealing happens to happen there.  So that is
not schizophrenic but quite the opposite.)

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

I agree, and if someone will write a good markdown to mdoc
converter then world dominition is only a small step away. ^_^
For what is shown in the middle of the bottom line of manuals
quite a furious mixture can be seen, including nothing at all.
So at least on the inhomogenous GNU/Linux environment i'm writing
this on the man(1)ual pages of the GNU tools wc(1), grep(1) and
find(1) differ in that the first shows "July 2015", the second
"GNU grep 2.22" and the last nothing (only "FIND(1)" in the lower
right).  (Starting in 2001 i wished regulary reoccurring to have
a BSD userland on a Linux kernel.  _That_ would be nice!)
But i for one disagree with the date format, since

 |> and (b) locale / charset agnostic and worldwide relatively (it
 |> is a Gregorian date in the end) easy perceivable.

it is at least neutral.
Granted there already is a world domination in the world of
programming and normal end-users will rarely see manual pages, and
even if it is a single entry of the last line of a manual page.

But YYYY-MM-DD could be easily converted to the calendar of
a locale user, which is not the case for the current format.
There is not even strptime_l(), so you either had to unroll
a parser or (less likely) setlocale() to C/POSIX in order to
strptime() the english names.

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

But this is today.  What will be in 20, 30 or even fourty years?
I think decisions have to be made with some context, and then the
above is plain unacceptable!  Helmut Schmidt for example pointed
out that whereas in the 1950s more than 25% of the worlds goods
(so to say) where "created" by the Europeans (or their slaves, of
course), it can be expected that in the middle of the century no
more than about 7% will remain.  Going the fortress way and
massively pushing own interest on the outside (just remember that
before Fischer/Schröder corruption in foreign countries was
tax-deductible in Germany!) does only seem to be the right way ...
unless the three fingers that point back at you are visible.  So
to say (ah, it's a monday).

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

You won't find one in me either.  I'm always stunned that suddenly
everything becomes so german on Linux, and was like that on Apple.
Talking about messages.  (My shared .profile only sets LC_ALL.
But there LC_MESSAGES really is necessary.  I mean it's fine and
great, *if* i could selectively install what i want.  E.g., about
15 years ago with earliest KDE it was terrible to see that all
those menu entry definition files contained all the available
translations.  And AlpineLinux doesn't install any manuals, but
that is also weird; wondering why their image is so much larger
than that of Void.)

 |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

But i don't agree nonetheless.  I think localized documentation is
very important and will be happily consumed if it's available.
No, and i don't think that people you meet at some conference will
be of any value in determining wether it is important or not.
Professionals tend to say things like "of course *everybody* knows
that and that" and whereas it's true it is so only for the people
they usually have contact with.  It's the outcome of an ivory
tower's point of view, and i guess that is true most of the time.

But even if.  That is today.  Outdated localized translations are
a management problem only -- simply don't bundle them!  (The
translation status of not few programs in the GNU/Linux world are
really good, i cannot comment on the translation quality, of
course.)  The future will bring many, many new users in places of
the world which are considered third world by ourselves.  And in
my opinion it is a matter of livable human co-existence to try to
offer support if available.

In this respect i would say that using english style dates was an
error right from the start, but which anyway should have been
corrected many years ago.  And whereas it may be easier to convert
the dates to some locale format as they are today, and talking
about roff macros, i think having a standardized variant like
YYYY-MM-DD will be better over time.  I.e., i think it may make
sense to offer a new date-localization troff command that can be
used from within man/mdoc/xy before the date is actually
displayed.  And why not giving the user an option to define her or
his preferred format in her or his ~/.roffrc or so?  And then
troff has the same problem with strptime() that i pointed out
above.  (And not to talk about true calendar support that is
humiliatingly missing from ISO C and POSIX.)

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

So i continue to disagree due to the reasons as above.  I think
i will not only retain the idea of the RFC 3339 "full-date"
format, but also extend my (future) troff to support date and time
localization, such functionality is missing iirc.
Ciao,

--steffen
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

  reply	other threads:[~2015-11-16 13:35 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         ` Mdocdate Ingo Schwarze
2015-11-16 13:35           ` Steffen Nurpmeso [this message]
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=20151116133544.XUCkX-64J%sdaoden@yandex.com \
    --to=sdaoden@yandex.com \
    --cc=discuss@mdocml.bsd.lv \
    --cc=schwarze@usta.de \
    --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).