It's a typo in the manual. Fixing it now.

Where exactly in the manual do you find this? I couldn't find it.

i guess it is in the PDF version?

it is a known problem (at least to me ) that the
TeX backend converts a '--' into a 'long -'

Forwarded to the doc group, it's only a mistake in the pdf version of tha manual.

but it _is_ a documentation problem, even if it only affects part of the output formats (it should be visible in the postscript version too)

so let's do not close it until it is solved

Resurfacing... I also once saw something like <<< being rendered strangely in PDF.

When the PDF versions come back online (really soon now),
this will be fixed with a terrible hack. Which means running
the xml files through the following perl script before
compiling...

#!/usr/bin/perl -pi

s/([^!])-{2}([^>])/$1-\ -$2/g;
s/\<\</\<\ \</g;
s/\>\>/\>\ \>/g;

IIRC, somebody committed a hack to PDF generation to get <<< and -- correct, but in the latest PDF I notice that <<< is still incorrect, but -- is correct.

This is not a bug. It is a well known feature. If you use LaTeX you should know this.
-Egon

I use LaTeX a lot, and of course I know this feature, but that's not the point here!

Please read the report carefully before closing.

Reopening

The same goes for myself by the way: Now I recall where I read about that hack, it's in this very bug report... :-/

But that hack isn't in repository, Hartmut, is it okay for me to see wether I can add it in the repo?

This "bug" is not a documentation problem. Building PostScript or PDF manuals with xml files renders two dashes into a long dash. This is a problem with Jade because it uses TeX. 

The "<" is another case. It is the first character for an element name in XML. This means, you cannot write a "<" character in the CDATA section of any XML file. Only ">" is allowed.

Please use the mailinglist archives, it was discussed several times.

I think Egon meant:

| This means, you cannot write a "<" character
| __outside__ a CDATA section of any XML file.
| Only ">" is allowed.

Extract from:
http://www.w3.org/TR/2000/REC-xml-20001006#sec-cdata-sect

| Within a CDATA section, only the CDEnd string is
| recognized as markup, so that left angle brackets and
| ampersands may occur in their literal form; they need
| not (and cannot) be escaped using "&lt;" and "&amp;".

So people can use < in CDATA. Outside CDATA, they can't.

--
Goba

as long as we produce manual versions 
with missleading output of '--'
this *is* a documentation bug

it is not our fault that it shows up
as the real cause for it is a shortcoming
of Jade which doesn't take in account 
that '--' has a special meaning in
TeX and doesn't add escape characters
or sequences to prevent this, but as
we prodcude the wrong output with the
current toolchain it *is* a documentation
bug, problem, misfeature ... whatever ...
after all 

so this report should not be closed unless 
we get a non-ugly solution for it

whe can talk about 'suspended' with jah's 
dirty hack in place, but definetly not
about 'closed' as the problem isn't solved
yet!

This is still a documentation problem, since in the PDF version it shows $i- instead of $i--, and that is wrong. It's not about the tools, it's about the result! (and we are providing a PDF version, if it were users generating PDF files, it would indeed not have been a doc problem, but since WE are doing it, it IS a doc problem.)

It is not a problem in the XML files, but a bug c.q. feature sowewhere between dvi -> pdf (since the dvi is okay with my dvi-viewer).

Also ps file seem to be okay. (hey, I see there is no download available in PS, why is that?)

I'll try to find some solution. Could be that the solution
is switching to Fop. In the meanwhile, it's going to be dirty
hacks. Unless someone actually knows how to fix TeX, jade or
something...

> Unless someone actually knows how to fix TeX,
> jade or something...

TeX does what it should do as documented
and i do not know how to fix 'something'
but i think i have found a simple solution
to deal with it in openjade sources

 i have just successfully created a TeX manual
 with a patched version of openjade-1.3

 the following patch has been submitted
 to the openjade project

--- openjade-1.3/jade/TeXFOTBuilder.cxx Fri Aug 13 22:28:29 1999
+++ openjade-1.3.hholzgra/jade/TeXFOTBuilder.cxx        Tue Oct  9 06:24:59 2001
@@ -1828,6 +1828,7 @@
 #endif
 void TeXFOTBuilder::characters(const Char *s, size_t n)
 {
+    static int l=-1;
   for (; n > 0; n--, s++) {
                                // Since TeX has only 256 characters
                                // by default, two-byte characters
@@ -1842,6 +1843,11 @@
                                // Otherwise, check for special
                                // TeX escapes.
       switch(*s) {
+            case '-':
+            case '<':
+            case '>':
+                if(l==*s) os() << "\\-";
+                // fallthru
       default:
        os() << char(*s);
 #ifdef OUTLINES
@@ -1891,6 +1898,7 @@
        break;
       }
     }
+        l=*s;
   }
 }