Date: Thu, 26 Aug 1999 21:18:30 +0100 From: Nik Clayton <nik@freebsd.org> To: Makoto MATSUSHITA <matusita@matatabi.or.jp> Cc: doc@freebsd.org, doc-jp@jp.freebsd.org Subject: Re: Japanese FAQ on the Web is broken Message-ID: <19990826211830.C86126@catkin.nothing-going-on.org> In-Reply-To: <19990826192109K.matusita@matatabi.or.jp>; from Makoto MATSUSHITA on Thu, Aug 26, 1999 at 07:21:09PM %2B0900 References: <19990826192109K.matusita@matatabi.or.jp>
next in thread | previous in thread | raw e-mail | index | archive | help
[ Sent to -doc and doc-jp, reply-to points back to -doc ] On Thu, Aug 26, 1999 at 07:21:09PM +0900, Makoto MATSUSHITA wrote: > > Sorry if this is a well-known bug. > > <URL:http://www.freebsd.org/ja/FAQ/FAQ.html>, the entry page of > FreeBSD FAQ written in Japanese is broken (all characters are not a > japanese character!). Thanks for the pointer. I think this is now fixed, but I'd appreciate confirmation. Please be aware that I will be unable to commit to the tree for the next 24 hours or so because I'll be away from the computer, so any other fixes that need doing will need to be carried out by someone else (Jun, Jesus, Chris Costello, and John Baldwin are all committers who could probably carry this out, assuming any patches you come up with work OK on their systems). > Why? Who break? First, please understand that I don't fully understand the i18n issue, and would be hard-pressed to tell a good page from a bad one. I am relying on people like yourself being able to point out problems and possible solutions in situations like this. Having said that. . . This is tied to the DocBook stylesheets that we use. As you can see if you look at any of the webpages produced by the stylesheets, they do more than just convert the DocBook pages to pretty HTML. They also add text to the pages. In particular, they add the navigation links at the top and the bottom, and a few other bits and pieces as well. In order for the stylesheets to do this, they need to know what language your document is written in. The stylesheets come with the words "Next", "Previous", "Home", and sundry other pieces of boilerplate text translated in to a variety of different languages, including Japanese. The "normal" way to tell the stylesheets what language your document is written in is to add the 'lang="xx"' attribute to the first element in your document. For example, the Japanese Handbook (or FAQ) should start <book lang="ja"> If you look at the Spanish FAQ you'll see it starts <book lang="es"> For reasons I don't fully understand (Jun Kuriyama is the expert here) this isn't working properly for the Japanese translation. I believe Jun has patches for this problem for the stylesheets, but they have not yet been incorporated in to the version we use (I think that's the case, but Jun might well correct me on this point). Because of this problem, we need to use a bit of a hack. If you look at the top of doc/share/sgml/freebsd.dsl, you'll see <!ENTITY % lang.ja "IGNORE"> and then further down <!-- Locatization --> <![ %lang.ja; [ <![ %lang.ja.dsssl; [ (define %gentext-language% "ja") ]]> (define %html-header-tags% '(("META" ("HTTP-EQUIV" "Content-Type") ("CON TENT" "text/html; charset=EUC-JP")))) ]]> This is a rather convoluted way of saying If the tools that process the Japanese documentation have the command line flag '-ilang.ja' passed to them, add the additional HTML header tags "Content-Type", and set it to "text/html; charset=EUC-JP". This is what your web browser is looking for before it will switch to using a Japanese font -- note that you could still have told your browser to use a Japanese font and the page would like fine, but it's that header in the HTML (do "View Source" in any of the Japanese HTML pages to see it) that tells your browser to do this automatically. Now, if you look at one of the Japanese Makefiles (say, for the FAQ, in doc/ja_JP.eucJP/books/faq/Makefile) and look at r1.2 of this file, you'll see a line JADEOPTS= -ilang.ja TIDYFLAGS= -raw Jade and Tidy are the two programs used to produce the HTML pages, and, as you can see, one of these variables is set to "-ilang.ja". So, in theory, those HTML meta-tags that I mentioned earlier will be included, and all will be well. According to the CVS logs, Jun Kuriyama added those entries on the 23rd (i.e., Monday this week). However, all was obviously not well, so what was the problem? We certainly used to have a variable called JADEOPTS. However, on the 5th of May this year (so over three months ago) I suddenly realised what seemed to be a Makefile convention. Namely, Makefiles often build up the command lines to the programs they are going to run piece by piece, and as they do this, they stuff the command line they are building into a variable called <PROGRAM>OPTS, where <PROGRAM> is the name of the program it's for. However, when you run make(1) you can add to these options on the command line (or in the Makefile) by defining a variable called <PROGRAM>FLAGS. See, for example, the C compiler, and the use of the COPTS and CFLAGS variables. Back on 5/5, I realised that when I created docproj.docbook.mk that I'd got the use of these two variables the wrong way round. So I switched them (this is documented in r1.3 of docproj.docbook.mk. The net effect is that although Jun had added "JADEOPTS= -ilang.ja" to the Makefile earlier this week, this option was never being passed on to Jade when it was run. So the HTML pages never had that meta tag added to them, and your browser didn't automatically switch to the correct encoding. The simple fix, which I've committed, is to change JADEOPTS in faq/Makefile and handbook/Makefile to JADEFLAGS. I built the FAQ and Handbook with this on freefall, and installed it on the website. To my untrained eye it now looks better -- at least the fonts that my browser is using look suitably Japanese. However, the least word on whether it is fixed or not will have to come from yourselves. If it is still broken, I hope the above description gives you a head start in working out what the problem is, and submitting a fix. > I've checked and found that other pages are also broken; As I say, the Handbook will also have been broken, and for the same reason. However, if there are any other pages that have the same problem could you please let me know about them? Thanks, N -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990826211830.C86126>