[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Install manual, Finnish translation STARTED

>>>>> "Ardo" == Ardo van Rangelrooij <avrangel@flevonet.nl> writes:
Ardo> Note that having the language indicator in the sgml source file
Ardo> name results using the current version of debiandoc-sgml in
Ardo> target file names with this same language indicator, also for
Ardo> html!!!  This may be ok for the other target formats, but
Ardo> certainly not for html: the name of the directory containing the
Ardo> html files is based on the source file name.  So instead of one
Ardo> directory with all the languages we get one directory per
Ardo> language.

Ardo> If this latter is what we want it's fine with me and I don't
Ardo> have to change anything.  I can also implement a mechanism to
Ardo> check whether the source file name has a language indicator
Ardo> and/or to check the environment for a language indication, but
Ardo> it's not so difficult to think about examples which go
Ardo> completely wrong here.

Ardo> Instead I propose a cleaner and more robust solution: Simply
Ardo> require that every debiandoc-sgml based source file has a
Ardo> language indicator, including those in English.  Then there's no
Ardo> guessing as to what language we're trying to process.  This also
Ardo> has the (minor, but still) advantage that there's no need to set
Ardo> the environment to get the document in the wanted language.  We
Ardo> only need to look at the source file name.  For now (for ever?)
Ardo> we could default to English.

I don't like how much you're breaking backwards compatability here.
I think it's *critical* that you don't all of a sudden start changing
how the output files are named.  Believe me, things are going to
break, break, break!

Let's give an example -- the boot floppies.  In that system, I need to
put at least *two* different output'd Debiandoc files into the same
dir -- all files need to be in a flattened dir with the boot floppies;
I use relative URLs to point to boot-floppies files such as
resc1440.bin, and this is used on (a) the web site (b) the debian
archive, and (c) the CD-ROM.  It's probably the most complex
debiandoc-sgml thing out there right now.

So, looking at one of the files:

These are the files produced by debiandoc2html (1.1.5):

<apharris@burrito:documentation> ls dselect-beginner.html/
ch-dselect-conclusion.en.html  ch-dselect-intro.en.html       index.en.html
ch-dselect-glossary.en.html    ch-dselect-main.en.html

Then I munge the files and move them (notably, move index.en.html to
dselect-beginner.en.html).  Also I have to make symlinks for content
negotiation, but I don't think that should be your problem:

<apharris@burrito:documentation> ls -nGl arch/i386/*dselect*
-rw-r--r--   1 421          1860 Feb 26 06:23 arch/i386/ch-dselect-conclusion.en.html
lrwxrwxrwx   1 421            29 Feb 26 06:24 arch/i386/ch-dselect-conclusion.html -> ch-dselect-conclusion.en.html
-rw-r--r--   1 421          1662 Feb 26 06:23 arch/i386/ch-dselect-glossary.en.html
lrwxrwxrwx   1 421            27 Feb 26 06:24 arch/i386/ch-dselect-glossary.html -> ch-dselect-glossary.en.html
-rw-r--r--   1 421          2305 Feb 26 06:23 arch/i386/ch-dselect-intro.en.html
lrwxrwxrwx   1 421            24 Feb 26 06:24 arch/i386/ch-dselect-intro.html -> ch-dselect-intro.en.html
-rw-r--r--   1 421         20730 Feb 26 06:23 arch/i386/ch-dselect-main.en.html
lrwxrwxrwx   1 421            23 Feb 26 06:24 arch/i386/ch-dselect-main.html -> ch-dselect-main.en.html
-rw-r--r--   1 421           844 Feb 26 06:23 arch/i386/dselect-beginner.en.html
-rw-rw-r--   1 421         63374 Feb 26 06:24 arch/i386/dselect-beginner.en.pdf
-rw-rw-r--   1 421         23763 Feb 26 06:23 arch/i386/dselect-beginner.en.txt
lrwxrwxrwx   1 421            24 Feb 26 06:24 arch/i386/dselect-beginner.html -> dselect-beginner.en.html
lrwxrwxrwx   1 421            23 Feb 26 06:24 arch/i386/dselect-beginner.pdf -> dselect-beginner.en.pdf
lrwxrwxrwx   1 421            23 Feb 26 06:24 arch/i386/dselect-beginner.txt -> dselect-beginner.en.txt

Ok, so what's my point.  My point is that you don't currently give
enough control over HTML file naming in debiandoc2html.

I suggest you use the scheme adopted by the docbook folks.  They use
processing instructions in the SGML:

  html-basename -- base filename for HTML, would be 'dselect-beginner' in my example

  html-filename -- name for the top-level file, would be
      'dselect-beginner.html' (um, but need to work out lang naming here...

  html-dir      -- name for directory to put files in, probably would be '.'

PIs in SGML are specified like so:

  <?html-dir html>

I think you should keep the *default* naming semantics just as they
are in potato.  Add a switch for debiandoc2* to use LANG naming.  Add
support for these PIs above, or alternatively, the equivalent as flags
to the programs.

Just my $.02.

.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>

Reply to: