From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01-web.scc.kit.edu (scc-mailout-kit-01-web.scc.kit.edu [129.13.231.93]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 5020d3cd for ; Sat, 14 Nov 2015 20:51:49 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1ZxmTo-0002zj-4e; Sun, 15 Nov 2015 02:51:46 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1ZxmTo-0004AG-2T; Sun, 15 Nov 2015 02:51:44 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84) (envelope-from ) id 1ZxmTn-0003mX-CW; Sun, 15 Nov 2015 02:51:44 +0100 Received: from localhost (1031@localhost [local]); by localhost (OpenSMTPD) with ESMTPA id a5ee02bc; Sun, 15 Nov 2015 02:51:43 +0100 (CET) Date: Sun, 15 Nov 2015 02:51:43 +0100 From: Ingo Schwarze To: Steffen Nurpmeso Cc: discuss@mdocml.bsd.lv Subject: Re: Mdocdate Message-ID: <20151115015143.GG22003@athene.usta.de> References: <86r3jva7s9.fsf@desk.des.no> <20151112213135.GL20023@athene.usta.de> <86r3jua1ja.fsf@desk.des.no> <20151114012201.GL7344@athene.usta.de> <20151114150201.btVpSjagp%sdaoden@yandex.com> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20151114150201.btVpSjagp%sdaoden@yandex.com> User-Agent: Mutt/1.5.23 (2014-03-12) Hi Steffen, Steffen Nurpmeso wrote on Sat, Nov 14, 2015 at 04:02:01PM +0100: > Ingo Schwarze 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