From: Steffen Nurpmeso <firstname.lastname@example.org> To: Ingo Schwarze <email@example.com> Cc: firstname.lastname@example.org Subject: Re: Mdocdate Date: Mon, 16 Nov 2015 14:35:44 +0100 [thread overview] Message-ID: <20151116133544.XUCkX-64Jemail@example.com> (raw) In-Reply-To: <20151115015143.GG22003@athene.usta.de> Hallo Ingo! Ingo Schwarze <firstname.lastname@example.org> wrote: |Steffen Nurpmeso wrote on Sat, Nov 14, 2015 at 04:02:01PM +0100: |> Ingo Schwarze <email@example.com> 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 firstname.lastname@example.org
next prev parent 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-64Jemail@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --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).