docutils-develop

[Docutils-develop] language set testing

[<eng...@ss...>]

attached a quick script that checks for language.labels
having all entries that en has.

and if language directives are found.

This is how i understood the datastructure, might be totally wrong.

Could be put into a test if correct (david ?).

Is it an error if rst.language has no language module but
languages has ? e.g. sk.

cheers

p.s. still no interest complaining about rst to latex to pdf conversions ?

-- 
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] language set testing

[David G. <go...@us...>]

eng...@ss... wrote:
> attached a quick script that checks for language.labels
> having all entries that en has.
> 
> and if language directives are found.
> 
> Could be put into a test if correct (david ?).

Certainly, with pleasure.  It needs a bit of work to make it more
general-purpose:

* The language codes should not be hard-coded, but determined
  dynamically from directory listings.

* The module should be converted to be compatible with unittest.py.
  See the other test modules, like docutils/test/test_utils.py.

Could you make these changes?  I'd also prefer to call it
"test_languages.py" (verbose is better).

> This is how i understood the datastructure, might be totally wrong.

The "labels" dict can be xor-compared (it's a mapping of English terms
to terms in the given language), but the "bibliographic_fields" dict
cannot (it's a mapping of terms in the given language to node
classes).  You'll notice that all the bibliographic_fields items
failed for de.py, even though they're correct.

The length of "bibliographic_fields" also cannot be compared, since
languages behave differently.  In Swedish there's no difference
between "Author" and "Authors", so there's one less entry.  Also, in
accented languages it may be useful to have both accented and
unaccented entries for versatility.

> Is it an error if rst.language has no language module but
> languages has ? e.g. sk.

That's a good question, and one that I've had myself.  I don't know
the answer.  If no parsers.rst.languages module exists for the
language, English is currently used as a fallback.

In programming languages, most people seem to be happy with
English-based syntax.  AppleScript had language dialects, but I don't
think it caught on (code in Japanese looked *very* strange to my eyes,
but I'm biased).  Directives are similar to programming language
keywords/statements/commands, but not the same.  What do people think?

Another question, from the to-do list: Should we use the language
module for directive option names?  In other words, should directive
option names be translated?

> p.s. still no interest complaining about rst to latex to pdf
> conversions ?

Sorry, I don't have a latex toolchain set up.  What are the
requirements?

Could you put an example PDF file in your sandbox?  (Directly on the
web site please, not under CVS.)

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] language set testing

[<gr...@us...>]

On Tue, 5 Nov 2002, David Goodger wrote:

> eng...@ss... wrote:
> > attached a quick script that checks for language.labels
> > having all entries that en has.
> >
> > and if language directives are found.
> >
> > Could be put into a test if correct (david ?).
>
> Certainly, with pleasure.  It needs a bit of work to make it more
> general-purpose:
>
> * The language codes should not be hard-coded, but determined
>   dynamically from directory listings.
>
> * The module should be converted to be compatible with unittest.py.
>   See the other test modules, like docutils/test/test_utils.py.
>
> Could you make these changes?  I'd also prefer to call it
> "test_languages.py" (verbose is better).

yes, but what can we check .. see below

and maybe this should be more visible to translators not only
a unittest, and could give warnings (verbose mode).

> > This is how i understood the datastructure, might be totally wrong.
>
> The "labels" dict can be xor-compared (it's a mapping of English terms
> to terms in the given language), but the "bibliographic_fields" dict
> cannot (it's a mapping of terms in the given language to node
> classes).  You'll notice that all the bibliographic_fields items
> failed for de.py, even though they're correct.

they failed because of first letter uppercase (i fixed this or
did i break something ? another test required!)

> The length of "bibliographic_fields" also cannot be compared, since

This was a try to test what might be possible, if not this
will be removed.

> languages behave differently.  In Swedish there's no difference
> between "Author" and "Authors", so there's one less entry.  Also, in

learned this from adam (maybe one could put comments in the
file for the next peer)

> accented languages it may be useful to have both accented and
> unaccented entries for versatility.
>
> > Is it an error if rst.language has no language module but
> > languages has ? e.g. sk.
>
> That's a good question, and one that I've had myself.  I don't know
> the answer.  If no parsers.rst.languages module exists for the
> language, English is currently used as a fallback.

tools/html.py -l de README.txt donotcare.html
says
  File "/home/bert/lib/python/docutils/parsers/rst/states.py", line 148, in run
    self.language = languages.get_language(
  File "/home/bert/lib/python/docutils/parsers/rst/languages/__init__.py", line
19, in get_language
    module = __import__(language_code, globals(), locals())
ImportError: No module named de

> In programming languages, most people seem to be happy with
> English-based syntax.  AppleScript had language dialects, but I don't
> think it caught on (code in Japanese looked *very* strange to my eyes,
> but I'm biased).  Directives are similar to programming language
> keywords/statements/commands, but not the same.  What do people think?

reST is no programming language, i thought the text should be a valid
document (as far as possible) otherwise we might need a text-writer.

and the test of course must know if it is required or optional.

> Another question, from the to-do list: Should we use the language
> module for directive option names?  In other words, should directive
> option names be translated?
>
> > p.s. still no interest complaining about rst to latex to pdf
> > conversions ?
>
> Sorry, I don't have a latex toolchain set up.  What are the
> requirements?

te_latex on my linux install this seams to include what is needed.
but if someone tries we will see clearer.

pdflatex is better as it can handle the pngs directly, so there
is no problem for needing eps-with bounding boxes (quality might
be nonoptimal though)

but within limits i offered to do conversions, not because test.txt
is too sick, but because we will learn more from different inputs.
e.g. i had to remove juliens pretty paladino font because it blows
up pdfs.
currently the latex output is a mixture of using latex's title
but not author or date. the table of contents is numbered by docutils
(because i have no interest in spending hours to find out how to
get the test.txt example of with the second table of contents into
latex)
i donot like the colored links ... asf.

> Could you put an example PDF file in your sandbox?  (Directly on the
> web site please, not under CVS.)

yessir, you mean the test.txt ? by consulting the latex2e-README.txt
one could see what i am pondering at too.

tools.pdf and test.pdf

-- 
 BINGO: innovative solutions
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] language set testing

[David G. <go...@py...>]

gr...@us... wrote:
> and maybe this should be more visible to translators not only
> a unittest, and could give warnings (verbose mode).

What do you mean?

>>> This is how i understood the datastructure, might be totally
>>> wrong.
>>
>> The "labels" dict can be xor-compared (it's a mapping of English
>> terms to terms in the given language), but the
>> "bibliographic_fields" dict cannot (it's a mapping of terms in the
>> given language to node classes).  You'll notice that all the
>> bibliographic_fields items failed for de.py, even though they're
>> correct.
>
> they failed because of first letter uppercase (i fixed this or
> did i break something ? another test required!)

I'm sorry, I mistakenly thought that "xor" was being applied to
"bibliographic_fields" in docutils/languages/de.py.

You're correct to have made the keys lowercase in
docutils/parsers/rst/languages/de.py.

BTW, de.py needs translations of the "raw", "include", and "replace"
directives.  Could you please?

There's a comment::

      'topic': 'topic',  # Inhalt, Thema or =DCberbegriff

There can be many keys with the same value.  Two of them anyway;
"inhalt" is already used for "contents".  Are they homonyms?

Another::

      'bild': 'image',
      'figure': 'figure', # also Bild ?

You can't use "bild" twice, but surely there's an appropriate word in
German?  Something like "titled-image" (translated) may suffice.  The
English "image" just means "picture", whereas "figure" has a larger
meaning, like "diagram/illustration/explanation".

I know no German, so I have to trust you as a native speaker to do
your best.  Just don't translate "contents" as "my hovercraft is full
of eels".  (Monty Python reference)

>> The length of "bibliographic_fields" also cannot be compared, since
>
> This was a try to test what might be possible, if not this
> will be removed.

Probably cannot be tested.

>> languages behave differently.  In Swedish there's no difference
>> between "Author" and "Authors", so there's one less entry.
>
> learned this from adam (maybe one could put comments in the file for
> the next peer)

Good idea.

>> If no parsers.rst.languages module exists for the
>> language, English is currently used as a fallback.
>
> tools/html.py -l de README.txt donotcare.html
...
>   File ".../docutils/parsers/rst/languages/__init__.py", line
> 19, in get_language
>     module =3D __import__(language_code, globals(), locals())
> ImportError: No module named de

Looks like a bug!  I should qualify: the *intention* is for English to
be used as a fallback for directive names.  Added to to-do/bugs.

>> In programming languages, most people seem to be happy with
>> English-based syntax.  AppleScript had language dialects, but I
>> don't think it caught on (code in Japanese looked *very* strange to
>> my eyes, but I'm biased).  Directives are similar to programming
>> language keywords/statements/commands, but not the same.  What do
>> people think?
>
> reST is no programming language,

I agree.

> i thought the text should be a valid document (as far as possible)
> otherwise we might need a text-writer.

Don't know what you mean by "we might need a text-writer".

> and the test of course must know if it is required or optional.

I think a test should fail if any aspect of a language isn't there.

>> Another question, from the to-do list: Should we use the language
>> module for directive option names?  In other words, should
>> directive option names be translated?

How about this one?  Right now in English we would write::

    .. contents:: :local:

In German, "contents" is translated, but "local" is not::

    .. inhalt:: :local:

So should directive options be translated too?

--=20
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] language set testing

[<gr...@us...>]

On Wed, 6 Nov 2002, David Goodger wrote:

> gr...@us... wrote:
> > and maybe this should be more visible to translators not only
> > a unittest, and could give warnings (verbose mode).
>
> What do you mean?

anyone doing a translation should start all_test, but at least
test_language.

> BTW, de.py needs translations of the "raw", "include", and "replace"
> directives.  Could you please?

i put the in as comments, dont know a proper word yet, would be a sentence.
but saying "include" in a document is not document content, but a processin=
g
command, the document would say "here the contents of xxx would be inserted=
"
or "see xxxx for details" but not "include". for me these are two
different audiences.

should we support both 'raw' and 'unbearbeitet'.

>
> There's a comment::

i like to comment, so i donot have to fetch TFM to know what i
thought last time.

>
>       'topic': 'topic',  # Inhalt, Thema or =DCberbegriff
>
> There can be many keys with the same value.  Two of them anyway;
> "inhalt" is already used for "contents".  Are they homonyms?

actually it is =FCberbegriff (a summarizing (herding) concept ?)
but this does not mean that this is the exact usage in document
processing. e.g. contents is something different for a book writer
an e-business monkey or a grocery worker.

inside the writer many things come as a topic and the writer has to
decide when it is a title, that is why topic_class is there.
so what is a topic: something summarizing (the title sums up the
document as does a chapter title ...)

but for me topic is also usable in german conversation.

i have to see in i18n to get the =FC right.

>
> Another::
>
>       'bild': 'image',
>       'figure': 'figure', # also Bild ?
>
> You can't use "bild" twice, but surely there's an appropriate word in
> German?  Something like "titled-image" (translated) may suffice.  The
> English "image" just means "picture", whereas "figure" has a larger
> meaning, like "diagram/illustration/explanation".

changed to "abbildung"

>
> I know no German, so I have to trust you as a native speaker to do
> your best.  Just don't translate "contents" as "my hovercraft is full
> of eels".  (Monty Python reference)

i am more in programming so thinking half english, as i understand
these are domain specific translations, so xp says get a domain expert.

> >> In programming languages, most people seem to be happy with
> >> English-based syntax.  AppleScript had language dialects, but I
> >> don't think it caught on (code in Japanese looked *very* strange to
> >> my eyes, but I'm biased).  Directives are similar to programming
> >> language keywords/statements/commands, but not the same.  What do
> >> people think?
> >
> > reST is no programming language,
>
> I agree.
>
> > i thought the text should be a valid document (as far as possible)
> > otherwise we might need a text-writer.
>
> Don't know what you mean by "we might need a text-writer".

if rest would be a programming language, like latex, or postscript
we might need a docutils/writers/text.py module.

>
> > and the test of course must know if it is required or optional.
>
> I think a test should fail if any aspect of a language isn't there.

yes, so your intention is "directives translation is optional"
so it is not an error if none is present, but if they are there
we test them.

>
> >> Another question, from the to-do list: Should we use the language
> >> module for directive option names?  In other words, should
> >> directive option names be translated?
>
> How about this one?  Right now in English we would write::
>
>     .. contents:: :local:
>
> In German, "contents" is translated, but "local" is not::
>
>     .. inhalt:: :local:
>
> So should directive options be translated too?

i had no need for directives up to know do not ask me about
directives options :-)

--=20
 BINGO: Lassen Sie sich was einfallen!
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] language set testing

[David G. <go...@py...>]

[David]
>> BTW, de.py needs translations of the "raw", "include", and "replace"
>> directives.  Could you please?

[Engelbert]
> i put the in as comments, dont know a proper word yet, would be a
> sentence.  but saying "include" in a document is not document
> content, but a processing command, the document would say "here the
> contents of xxx would be inserted" or "see xxxx for details" but not
> "include". for me these are two different audiences.

All I can suggest is to read the description in
http://docutils.sf.net/spec/rst/directives.html and decide on the best
word for your language.

> should we support both 'raw' and 'unbearbeitet'.

If "raw" is a German word, then sure.  Otherwise, it will be available
via the fall-back language, English.

>>       'topic': 'topic',  # Inhalt, Thema or =D0berbegriff
>>
>> There can be many keys with the same value.  Two of them anyway;
>> "inhalt" is already used for "contents".  Are they homonyms?
>=20
> actually it is =B8berbegriff (a summarizing (herding) concept ?)
> but this does not mean that this is the exact usage in document
> processing. e.g. contents is something different for a book writer
> an e-business monkey or a grocery worker.
...
> so what is a topic: something summarizing (the title sums up the
> document as does a chapter title ...)

"Contents" is short for "table of contents".  "Topic" is a kind of
self-contained subsection, or an admonition (like the "note"
directive) with its own title.  It's not a summary.  I suspect that
"=B8berbegriff" may not be the correct translation (but what do I know).

> inside the writer many things come as a topic and the writer has to
> decide when it is a title, that is why topic_class is there.

Don't understand.

> i am more in programming so thinking half english, as i understand
> these are domain specific translations, so xp says get a domain
> expert.

Or become one ;)

> so your intention is "directives translation is optional"
> so it is not an error if none is present, but if they are there
> we test them.

No, I think it should be an error if no directive translations are
present.

Idea (added to To Do list): the "test_language.py" module could test
all languages when run by "alltests.py", and it could accept a
language name argument if run as a script, like this::

    test_language.py de

If no argument, the default would be to test all language modules.

--=20
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] language set testing

[Adam C. <ad...@ch...>]

On Wed, 06 Nov 2002 21:26:26 -0500 David Goodger <go...@py...> wrote:

[...]
> So should directive options be translated too?

IMHO, yes. If we translate everything else, directive options should also be
translated. For consistency, if nothing else...

---
Adam Chodorowski <ad...@ch...>

File cabinet:
   A four drawer, manually activated trash compactor.

Re: [Docutils-develop] language set testing

[David G. <go...@py...>]

[David]
>> So should directive options be translated too?

[Adam]
> IMHO, yes. If we translate everything else, directive options should
> also be translated. For consistency, if nothing else...

So all we need now is an implementation...

[Docutils-develop] LaTeX/PDF critique

[David G. <go...@py...>]

Engelbert wrote:
>>> p.s. still no interest complaining about rst to latex to pdf
>>> conversions ?

Thanks for posting new PDFs.  For the benefit of others, here are the
URLs:

    http://docutils.sf.net/sandbox/grubert/tools.pdf
    http://docutils.sf.net/sandbox/grubert/test.pdf

These documents look *very* good!  You've made a lot of progress.

Some observations for tools.pdf:

* Since TeX uses curly quotes (which it expresses ``thusly''), perhaps
  the LaTeX writer could convert regular double-quotes to TeX-style
  quotes?  Or can TeX/LaTeX do that automatically?  Currently all
  double-quotes look like (just blur your eyes a bit ;)::

      99    99
        this

  whereas they should look like this::

      66    99
        this

  If it's not feasible to get proper curly quotes, then the Writer
  should use straight quotes.  Better to be ugly (straight quotes)
  than wrong (bad curlies).

  If the LaTeX Writer does this conversion, it should be careful *not*
  to do it for literal blocks and inline literals.  No curly quotes in
  Python code ;)

* Field lists should be rendered as two-column tables, like the
  docinfo fields.  See
  http://docutils.sf.net/spec/doctree.html#field-list ("Details"
  subsection, "Processing" item).

* In tools.pdf, the source text ``<directory>`` is being rendered as
  ``!directory?``, but with the inverse-! (&iexcl;) and inverse-?
  (&iquest;) characters.

* Shouldn't literal blocks be indented, or have some kind of
  decoration (solid left margin, etc.)?  I think relying on the
  typeface is too subtle; indentation helps distinguish literal blocks
  from the surrounding text.  Inline literals look fine the way they
  are.

* (I'm sure you already are aware of this.)  The table in tools.pdf,
  which is longer than one page, is not breaking across page
  boundaries.  Also, the paragraphs inside table cells are being
  merged together (ISTR this coming up before).

* Table column widths can be taken from the "colwidth" attributes of
  "colspec" elements in the doctree.  Attribute values are relative
  numbers, originating from the number of character columns in the
  source text.  For tools.txt, the table's colwidth values are "20"
  and "50", so the first column should be 2/7 and the second column
  5/7 wide.

And test.pdf:

* Bibliographic field lists (docinfo) should have ":" appended to each
  field name.

* I see you got the address line-breaking right.  Great!

* The "dedication" and "abstract" bibliographic fields get transformed
  to "topic" elements, specifically <topic class="dedication"> and
  <topic class="abstract"> in the internal doctree.  Topic should be
  rendered like sections (i.e., title above the body), only indented
  or otherwise set off from the rest of the document.  See
  http://docutils.sf.net/spec/doctree.html#topic .

* It would be useful if "problematic" elements acted as internal
  references to their system messages.  Back-links are also useful,
  for system messages as well as for footnotes and citations.

* From doctree.txt, definition list terms and classifiers "should be
  separated visually, typically by spaces plus a colon or dash."  I'd
  recommend a colon, so the input looks like the output:

      term : classifier
          definition...

* I'd recommend that option list tables *not* have visible borders and
  row/column separators.

* From test.pdf, section 2.10, I guess that it's hard to render
  complex tables properly in LaTeX? ;)

* The "image" directive in section 2.14.2 is producing an *inline*
  image, whereas it should be a block element (flush left, separated
  by a blank line from the text above & below).

* Why does the "figure" (section 2.14.2) appear at the very end of the
  document?  I could understand it floating to the top or bottom of
  the page it appears on, but it moves too far.

* Why are footnotes (a) mostly at the end of the document, and (b)
  spaced so far apart?

* In line blocks, all whitespace is significant.  Look at the stanza
  beginning "But can a bee be said to be" in section 2.14.5; each line
  should be indented more than the last.

  The same thing applies to inline literals, although to a lesser
  extent.  In other words, it would be nice to have significant
  whitespace there, but not crucial.  Using a recent browser, look at
  the whitespace in the inline literals in the second paragraph of
  http://docutils.sf.net/tools/test.html#inline-markup .

* The admonitions ought to be more distinctive.  They should jump out
  at the reader.  There are degrees of alerts.  The HTML Writer shows
  a little bit of what I mean, but it should be more distinctive too.

Please feel free to take this list and incorporat it in your To-Do
list.

I bet you're learning a lot about LaTeX!

Do you consider the Writer ready to migrate into the docutils package?
It doesn't have to be perfect, just `reasonably complete`_ as I've
defined before.  I didn't notice anything missing from test.pdf, so it
looks like it is reasonably complete.  I'd like to review the code
first though; please let me know if you think its ready.

.. _reasonably complete:
   http://docutils.sf.net/spec/notes.html#reasonably-complete

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-develop] Re: LaTeX/PDF critique

[<gr...@us...>]

On Wed, 6 Nov 2002, David Goodger wrote:

> Thanks for posting new PDFs.  For the benefit of others, here are the
> URLs:
>
>     http://docutils.sf.net/sandbox/grubert/tools.pdf
>     http://docutils.sf.net/sandbox/grubert/test.pdf
>
> These documents look *very* good!  You've made a lot of progress.

julien did the table stuff and i think we both learned a lot about
latexs table and other commands by this.

> Some observations for tools.pdf:
>
> * Since TeX uses curly quotes (which it expresses ``thusly''), perhaps
>   the LaTeX writer could convert regular double-quotes to TeX-style
>   quotes?  Or can TeX/LaTeX do that automatically?  Currently all
>   double-quotes look like (just blur your eyes a bit ;)::
>
>       99    99
>         this
>
>   whereas they should look like this::
>
>       66    99
>         this
>
>   If it's not feasible to get proper curly quotes, then the Writer
>   should use straight quotes.  Better to be ugly (straight quotes)
>   than wrong (bad curlies).

is in the todo (latex2e-README.txt (someday i wipe my sand/dustbox))


>   If the LaTeX Writer does this conversion, it should be careful *not*
>   to do it for literal blocks and inline literals.  No curly quotes in
>   Python code ;)
>
> * Field lists should be rendered as two-column tables, like the
>   docinfo fields.  See
>   http://docutils.sf.net/spec/doctree.html#field-list ("Details"
>   subsection, "Processing" item).

i want to stay away of tables as long as possible. in latex you
have tabular, tabularx, supertabular, longtable, ltxtable and
table. some are duplicates or extensions. but there is more than
one table environment. e.g. some tables may not be broken so
i use tabular, but then it might be moved around.

i would go for decriptions for docinfo fields too, this is like:

<b>field:</b> the description breaking here
  and continuing intended.

<b>another:</b> some other ...

the reason why i donot use it is the space between the entries.
but these are much easier than tables.

>
> * In tools.pdf, the source text ``<directory>`` is being rendered as
>   ``!directory?``, but with the inverse-! (&iexcl;) and inverse-?
>   (&iquest;) characters.
>
> * Shouldn't literal blocks be indented, or have some kind of
>   decoration (solid left margin, etc.)?  I think relying on the
>   typeface is too subtle; indentation helps distinguish literal blocks
>   from the surrounding text.  Inline literals look fine the way they
>   are.

donot talk about intendation (see test.txt line_block) latex
is sovereign over space vertical and horicontal.

> * (I'm sure you already are aware of this.)  The table in tools.pdf,
>   which is longer than one page, is not breaking across page
>   boundaries.  Also, the paragraphs inside table cells are being
>   merged together (ISTR this coming up before).

i did not have a look at it, packed tools.pdf just because
i wanted a real document, not only the test. but the breaking
environment is already in todo.

> * Table column widths can be taken from the "colwidth" attributes of
>   "colspec" elements in the doctree.  Attribute values are relative
>   numbers, originating from the number of character columns in the
>   source text.  For tools.txt, the table's colwidth values are "20"
>   and "50", so the first column should be 2/7 and the second column
>   5/7 wide.
>
> And test.pdf:
>
> * Bibliographic field lists (docinfo) should have ":" appended to each
>   field name.
>
> * I see you got the address line-breaking right.  Great!
>
> * The "dedication" and "abstract" bibliographic fields get transformed
>   to "topic" elements, specifically <topic class="dedication"> and
>   <topic class="abstract"> in the internal doctree.  Topic should be
>   rendered like sections (i.e., title above the body), only indented
>   or otherwise set off from the rest of the document.  See
>   http://docutils.sf.net/spec/doctree.html#topic .

i know: latex has an abstract environment and thanks (a footnote to
the document title), but as described earlier, i am not sure about
the direction. we use pagenumbering from latex and section numbering
from docutils (docutils has sectionnumbering because html does not have
it, but docutils uses <ol> numbering from html).

> * It would be useful if "problematic" elements acted as internal
>   references to their system messages.  Back-links are also useful,
>   for system messages as well as for footnotes and citations.

i tried to get the picture, linking except the bookmarks, are by
julien. so more to learn for me.

>
> * From doctree.txt, definition list terms and classifiers "should be
>   separated visually, typically by spaces plus a colon or dash."  I'd
>   recommend a colon, so the input looks like the output:
>
>       term : classifier
>           definition...
>
> * I'd recommend that option list tables *not* have visible borders and
>   row/column separators.

i too ?

> * From test.pdf, section 2.10, I guess that it's hard to render
>   complex tables properly in LaTeX? ;)

because it is hard.
latex does it great (for me). up to know i seldom used multicolumns
not speaking of multirows.

what we might learn from latex is longtables have
  header for first page : e.g. column headings
  footer                : "continued on next page" (could be generated by
                          docutils).
  header on following pages : "continued from previous page" and the
                          column headings
  footer on last page   : plain line.

> * The "image" directive in section 2.14.2 is producing an *inline*
>   image, whereas it should be a block element (flush left, separated
>   by a blank line from the text above & below).
>
> * Why does the "figure" (section 2.14.2) appear at the very end of the
>   document?  I could understand it floating to the top or bottom of
>   the page it appears on, but it moves too far.

latex figures are moveable (as are tables, what should it do if it
does not fit on this page) therefore a reference to a figure says
"see fig.132" and there is a "list of figures".

<SNIP>
> Please feel free to take this list and incorporat it in your To-Do

feel free to do it yourself :-) my sandbox has no fence.

> I bet you're learning a lot about LaTeX!
>
> Do you consider the Writer ready to migrate into the docutils package?
> It doesn't have to be perfect, just `reasonably complete`_ as I've
> defined before.  I didn't notice anything missing from test.pdf, so it
> looks like it is reasonably complete.  I'd like to review the code
> first though; please let me know if you think its ready.

for me it is ready, except for one or two things
BUG all enumerations start at one.
BUG enumerations can not nest ad lib.

then i would have real documents: i go for the docutils documentation.
tools/test.txt is then used to make short snippets of problemtatic
constructs.

review and criticize

-- 
 BINGO:
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] Re: LaTeX/PDF critique

[David G. <go...@py...>]

[David] 
>> * Shouldn't literal blocks be indented, or have some kind of
>>   decoration (solid left margin, etc.)?  I think relying on the
>>   typeface is too subtle; indentation helps distinguish literal
>>   blocks from the surrounding text.  Inline literals look fine the
>>   way they are.

[Engelbert]
> donot talk about intendation (see test.txt line_block) latex
> is sovereign over space vertical and horicontal.

If that's true, then LaTeX is forcing you to mis-format your document.
Perhaps the literal block (or verbatim or whatever) primitive doesn't
support indentation.  In that case, put it inside a block quote that
*does* allow indentation.

I treat HTML as a set of primitives.  I try to keep the generated HTML
documents "clean", but only where practical.  Don't try to create
pristine TeX output if it's just that: output.  Sometimes faking it is
OK.

>> * The "dedication" and "abstract" bibliographic fields get
>>   transformed to "topic" elements, specifically <topic
>>   class="dedication"> and <topic class="abstract"> in the internal
>>   doctree.  Topic should be rendered like sections (i.e., title
>>   above the body), only indented or otherwise set off from the rest
>>   of the document.  See
>>   http://docutils.sf.net/spec/doctree.html#topic .
> 
> i know: latex has an abstract environment and thanks (a footnote to
> the document title), but as described earlier, i am not sure about
> the direction.

I don't follow.

> we use pagenumbering from latex and section numbering from docutils
> (docutils has sectionnumbering because html does not have it, but
> docutils uses <ol> numbering from html).

What does this have to do with anything?

>> * Why does the "figure" (section 2.14.2) appear at the very end of
>>   the document?  I could understand it floating to the top or
>>   bottom of the page it appears on, but it moves too far.
> 
> latex figures are moveable (as are tables, what should it do if it
> does not fit on this page) therefore a reference to a figure says
> "see fig.132" and there is a "list of figures".

But there's no reason for a figure to move all the way to the end of
the document.  Could it be because the image is so large?  (IIRC,
TeX's algorithm for things too big to put on a page is to try them on
the next page, but if the thing is too large for *any* page,
degenerate cases may result.)

Again, if the TeX environment is fighting you, don't use the TeX
environment.  Just fake it.

>> Please feel free to take this list and incorporat it in your To-Do
> 
> feel free to do it yourself :-) my sandbox has no fence.

Just a suggestion, take it or leave it as you like.  I've got plenty
on *my* To-Do list, thanks.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Re: LaTeX/PDF critique

[engelbert g. <be...@ch...>]

On Fri, 8 Nov 2002, David Goodger wrote:

> [David]
> >> * Shouldn't literal blocks be indented, or have some kind of
> >>   decoration (solid left margin, etc.)?  I think relying on the
> >>   typeface is too subtle; indentation helps distinguish literal
> >>   blocks from the surrounding text.  Inline literals look fine the
> >>   way they are.
>
> [Engelbert]
> > donot talk about intendation (see test.txt line_block) latex
> > is sovereign over space vertical and horicontal.
>
> If that's true, then LaTeX is forcing you to mis-format your document.
> Perhaps the literal block (or verbatim or whatever) primitive doesn't
> support indentation.  In that case, put it inside a block quote that
> *does* allow indentation.

david currently i am happy that this and the address docinfo does
correct linebreak. this is done inside encode (which does more and more,
and could you have a quick glance at it, if you could think of
another way to do it).

> I treat HTML as a set of primitives.  I try to keep the generated HTML
> documents "clean", but only where practical.  Don't try to create
> pristine TeX output if it's just that: output.  Sometimes faking it is
> OK.

then latex might be not optimal, latex is made to enforce layout rules
that the users never thought of (IMHO)
maybe another possibility would beto use tex not latex, but not for now.

> >> * The "dedication" and "abstract" bibliographic fields get
> >>   transformed to "topic" elements, specifically <topic
> >>   class="dedication"> and <topic class="abstract"> in the internal
> >>   doctree.  Topic should be rendered like sections (i.e., title
> >>   above the body), only indented or otherwise set off from the rest
> >>   of the document.  See
> >>   http://docutils.sf.net/spec/doctree.html#topic .
> >
> > i know: latex has an abstract environment and thanks (a footnote to
> > the document title), but as described earlier, i am not sure about
> > the direction.
>
> I don't follow.

\begin{abstract}
this and that
\end{abstract}

is the way to add an abstract in latex, which then puts it in correct
place.

> > we use pagenumbering from latex and section numbering from docutils
> > (docutils has sectionnumbering because html does not have it, but
> > docutils uses <ol> numbering from html).
>
> What does this have to do with anything?

the html writer generates the section numbering, but does not
generate the ol-numbering.

in latex the writer could allow latex to generate section and
ol-numbering.

> >> * Why does the "figure" (section 2.14.2) appear at the very end of
> >>   the document?  I could understand it floating to the top or
> >>   bottom of the page it appears on, but it moves too far.
> >
> > latex figures are moveable (as are tables, what should it do if it
> > does not fit on this page) therefore a reference to a figure says
> > "see fig.132" and there is a "list of figures".
>
> But there's no reason for a figure to move all the way to the end of
> the document.  Could it be because the image is so large?  (IIRC,
> TeX's algorithm for things too big to put on a page is to try them on
> the next page, but if the thing is too large for *any* page,
> degenerate cases may result.)

you described it correct i guess.

> >> [DG] Please feel free to take this list and incorporat it in your
> >> To-Do
> >
> > [EG] feel free to do it yourself :-) my sandbox has no fence.
>
> [DG] Just a suggestion, take it or leave it as you like.  I've got
> plenty on *my* To-Do list, thanks.

i meant you could put it into my todo, not you should fix it.

although if you find some time to make a code review this could help
both of us, because you also are writing a writer. if you do review
just make comments like # BUG or so.

cheers

--
engelbert gruber
email: eng...@ss...

Re: [Docutils-develop] Re: LaTeX/PDF critique

[Simon B. <Sim...@un...>]

gr...@us... (gr...@us...) wrote:
> On Wed, 6 Nov 2002, David Goodger wrote:
> > * Since TeX uses curly quotes (which it expresses ``thusly''), perhaps
> >   the LaTeX writer could convert regular double-quotes to TeX-style
> >   quotes?  Or can TeX/LaTeX do that automatically?  Currently all
> >   double-quotes look like (just blur your eyes a bit ;)::
> >
> >       99    99
> >         this
> >
> >   whereas they should look like this::
> >
> >       66    99
> >         this
> >
> >   If it's not feasible to get proper curly quotes, then the Writer
> >   should use straight quotes.  Better to be ugly (straight quotes)
> >   than wrong (bad curlies).
> 
> is in the todo (latex2e-README.txt (someday i wipe my sand/dustbox))

Whee! Typographically correct quotes!

I'd just like to point out, that this is something that differs a bit
in different languages. In Germany the following is used:

                 66
            this
         99

Also there are the options

          >> this <<    (german)

and       << this >>    (french IIRC)

It would be *very* cool if one could select this somehow.  :-)


Bye,
        Simon

PS: I am very happy about the inline target stuff. Thanks David!

-- 
      Sim...@un...       http://www.home.unix-ag.org/simon/

Re: [Docutils-develop] Re: LaTeX/PDF critique

[<eng...@ss...>]

On Sun, 17 Nov 2002, Simon Budig wrote:

> gr...@us... (gr...@us...) wrote:
> > On Wed, 6 Nov 2002, David Goodger wrote:
> > > * Since TeX uses curly quotes (which it expresses ``thusly''), perhaps
> > >   the LaTeX writer could convert regular double-quotes to TeX-style
> > >   quotes?  Or can TeX/LaTeX do that automatically?  Currently all
> > >   double-quotes look like (just blur your eyes a bit ;)::
> > >
> > >       99    99
> > >         this
> > >
> > >   whereas they should look like this::
> > >
> > >       66    99
> > >         this
> > >
> > >   If it's not feasible to get proper curly quotes, then the Writer
> > >   should use straight quotes.  Better to be ugly (straight quotes)
> > >   than wrong (bad curlies).
> >
> > is in the todo (latex2e-README.txt (someday i wipe my sand/dustbox))
>
> Whee! Typographically correct quotes!
>
> I'd just like to point out, that this is something that differs a bit
> in different languages. In Germany the following is used:
>
>                  66
>             this
>          99

should work in the last cvs (maybe a week or so).

> Also there are the options
>
>           >> this <<    (german)
>
> and       << this >>    (french IIRC)

should be possible to be done similar than the quotes. but this means
we sooner or later start parsing the text. up to now the writer just
did markups. (just to note)

whatfore are the << bracketts used typographically i mean.

> It would be *very* cool if one could select this somehow.  :-)

selection should be automatic (IMHO) by -l de for german.

-- 
 BINGO: assertively disseminate unique opportunities
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] LaTeX/PDF critique

[Julien T. L. <me...@fr...>]

On Nov 6, 2002, at 21:29, David Goodger  was heard saying:

> These documents look *very* good!  You've made a lot of progress.

IMHO, they look way better using the stylesheet I provided--in particular, it
mostly solves the footnote problem.

I guess things will become easier if I commit my changes myself ;)

Oh, and, *thanks* David, for being less lazy than we are, and preparing a
to-do list... You last mail is now flagged as 'important' in my mailbox :)

Cheers,
-- 
Julien T. Letessier                   aim: JLetessier
Post-graduate ENSIMAG Student         web: http://www.mezis.net
IMAG IVR Master Student               email: co...@me...
---------------------------------------------------------------
SourceForge projects:
Solarpack: Distributing free software for Solaris
Docutils:  Python documentation framework
---------------------------------------------------------------

Re: [Docutils-develop] LaTeX/PDF critique

[<gr...@us...>]

On Mon, 11 Nov 2002, Julien T. Letessier wrote:

> On Nov 6, 2002, at 21:29, David Goodger  was heard saying:
>
> > These documents look *very* good!  You've made a lot of progress.
>
> IMHO, they look way better using the stylesheet I provided--in particular, it
> mostly solves the footnote problem.
>
> I guess things will become easier if I commit my changes myself ;)

i did commit your changes, didn't i ?


-- 
 BINGO: completely leverage other's inexpensive benefits
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] LaTeX/PDF critique

[<gr...@us...>]

> > On Mon, 11 Nov 2002, Julien T. Letessier wrote:
> >
> > > On Nov 6, 2002, at 21:29, David Goodger  was heard saying:
> > >
> > > > These documents look *very* good!  You've made a lot of progress.
> > >
> > > IMHO, they look way better using the stylesheet I provided--in particular,
it
> > > mostly solves the footnote problem.
> > >
> > > I guess things will become easier if I commit my changes myself ;)
> >
> > i did commit your changes, didn't i ?
>
> sorry, my mistake---i didn't send the last updates :)
> anyways, i'll commit them myself next time!

i want to propose some changes:

style.tex should hold: the font (as sayed earlier palatino make pdfs bigger)

settings required for proper layout should be set by the writer (written
to the output): this concerns your solution for footnotes and figures.

the inclusion of the style file should be done after setting defaults,
so there is a possibility to overwrite defaults.

caveats: if an option is given to the documentclass other packages
  recognize it automatically (at least i read so), otherwise every
  concerned package needs the option (it said so in th FM).

and we need documented stylefiles so people have an idea what to use
it for.

-- 
 BINGO: next-generation Outsourcing
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

[Docutils-develop] Re: Style sheet [was: LaTeX/PDF critique]

[Julien L. <me...@fr...>]

On mardi, nov 12, 2002, at 07:59 Europe/Paris, 
gr...@us... wrote:

> style.tex should hold: the font (as sayed earlier palatino make pdfs 
> bigger)
>
> settings required for proper layout should be set by the writer 
> (written
> to the output): this concerns your solution for footnotes and figures.

sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's 
what you mean)

> the inclusion of the style file should be done after setting defaults,
> so there is a possibility to overwrite defaults.

yep, I'm perfectly okay ith that.

> caveats: if an option is given to the documentclass other packages
>   recognize it automatically (at least i read so), otherwise every
>   concerned package needs the option (it said so in th FM).

As  a TeXnician, I've always considered as a bad habit using 
'documentclass' options to set defaults for the various packages -- 
rather specify the options exactly when needed. But if it makes your 
life easier, fine.

One point though -- I think we should keep the 'geometry' package 
included -- the '\geometry' command can be used in the stylesheet to 
modify the settings.

> and we need documented stylefiles so people have an idea what to use
> it for.

You mean, provide a few documented examples?

Cheers,

-- julien

Re: [Docutils-develop] Re: Style sheet [was: LaTeX/PDF critique]

[<gr...@us...>]

On Sun, 17 Nov 2002, Julien Letessier wrote:

> On mardi, nov 12, 2002, at 07:59 Europe/Paris,
> gr...@us... wrote:
>
> > style.tex should hold: the font (as sayed earlier palatino make pdfs
> > bigger)
> >
> > settings required for proper layout should be set by the writer
> > (written
> > to the output): this concerns your solution for footnotes and figures.
>
> sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's
> what you mean)

correct

> > the inclusion of the style file should be done after setting defaults,
> > so there is a possibility to overwrite defaults.
>
> yep, I'm perfectly okay ith that.
>
> > caveats: if an option is given to the documentclass other packages
> >   recognize it automatically (at least i read so), otherwise every
> >   concerned package needs the option (it said so in th FM).
>
> As  a TeXnician, I've always considered as a bad habit using
> 'documentclass' options to set defaults for the various packages --
> rather specify the options exactly when needed. But if it makes your
> life easier, fine.

this was just a note, i donot know anything more about it.

i just learned this recently, and if have no idea how much this is needed.
this way we would not have to know which package uses which option,
but then again we might have to know what options to give to
documentclass.

> One point though -- I think we should keep the 'geometry' package
> included -- the '\geometry' command can be used in the stylesheet to
> modify the settings.

fine with me.

> > and we need documented stylefiles so people have an idea what to use
> > it for.
>
> You mean, provide a few documented examples?

yes

-- 
 BINGO: best of breed products and services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] Re: Style sheet [was: LaTeX/PDF critique]

[<gr...@us...>]

On Sun, 17 Nov 2002, Julien Letessier wrote:

> On mardi, nov 12, 2002, at 07:59 Europe/Paris,
> gr...@us... wrote:
>
> > style.tex should hold: the font (as sayed earlier palatino make pdfs
> > bigger)
> >
> > settings required for proper layout should be set by the writer
> > (written
> > to the output): this concerns your solution for footnotes and figures.
>
> sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's
> what you mean)
>
> > the inclusion of the style file should be done after setting defaults,
> > so there is a possibility to overwrite defaults.
>
> yep, I'm perfectly okay ith that.
>
> > caveats: if an option is given to the documentclass other packages
> >   recognize it automatically (at least i read so), otherwise every
> >   concerned package needs the option (it said so in th FM).
>
> As  a TeXnician, I've always considered as a bad habit using
> 'documentclass' options to set defaults for the various packages --
> rather specify the options exactly when needed. But if it makes your
> life easier, fine.
>
> One point though -- I think we should keep the 'geometry' package
> included -- the '\geometry' command can be used in the stylesheet to
> modify the settings.
>
> > and we need documented stylefiles so people have an idea what to use
> > it for.
>
> You mean, provide a few documented examples?
>
> Cheers,
>
> -- julien
>
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by: To learn the basics of securing
> your web site with SSL, click here to get a FREE TRIAL of a Thawte
> Server Certificate: http://www.gothawte.com/rd524.html
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>

-- 
 BINGO: best of breed products and services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] Re: Style sheet [was: LaTeX/PDF critique]

[<gr...@us...>]

sorry i try once again

On Sun, 17 Nov 2002, Julien Letessier wrote:

> On mardi, nov 12, 2002, at 07:59 Europe/Paris,
> gr...@us... wrote:
>
> > style.tex should hold: the font (as sayed earlier palatino make pdfs
> > bigger)
> >
> > settings required for proper layout should be set by the writer
> > (written
> > to the output): this concerns your solution for footnotes and figures.
>
> sounds logical. i'll hard-code my TeX hacks into latex2e.py (if that's
> what you mean)

yes

> > the inclusion of the style file should be done after setting defaults,
> > so there is a possibility to overwrite defaults.
>
> yep, I'm perfectly okay ith that.

a suggestion from me, do you think it will work or must we expect
that some packages donot allow re-use or will collide.

> > caveats: if an option is given to the documentclass other packages
> >   recognize it automatically (at least i read so), otherwise every
> >   concerned package needs the option (it said so in th FM).
>
> As  a TeXnician, I've always considered as a bad habit using
> 'documentclass' options to set defaults for the various packages --
> rather specify the options exactly when needed. But if it makes your
> life easier, fine.

as a simple latex user i have no opinion. just tell what i read.
i am only concerned to not code to much knowledge (which package needs
which options) into the writer.

> One point though -- I think we should keep the 'geometry' package
> included -- the '\geometry' command can be used in the stylesheet to
> modify the settings.
>
> > and we need documented stylefiles so people have an idea what to use
> > it for.
>
> You mean, provide a few documented examples?

yes. should go into latex writer doc (=docs/latex_writer.txt ?)

-- 
 BINGO: Sind Sie flexibel?
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+