doxygen-develop — List for discussing new features, submitting patches, etc.

[Doxygen-develop] New language? What about Fortran?

[Xavier O. <xav...@an...>]

Hi,

I have just talked to a University professor that would be interested
in a version of Doxygen to process Fortran files.
I think there would be a lot of potential users for this language.
I do not pretend to do that. Maybe the fastest and easiest thing to do
is to add that to item 27 in the todo-wish list
at http://www.stack.nl/~dimitri/doxygen/todo.html.

BTW, it's not really up to date. Java is now a language that
is treated by Doxygen.

Greetings,

Xavier.

PS: If you could tell more precise requirement for this work,
I could try to send an announce to some of my contacts. I'm
not able to use newsgroup where it could be certainly efficient
to find the right people... if they have time, I know.

[Doxygen-develop] [i18n] French localiszation updated

[Xavier O. <xav...@an...>]

Hi,

 - translator_fr.h updated
I have updated translator_fr.h according to translator_report.txt.
The following methods
  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trIncludeFile()
  QCString trVerbatimText(const char *f)
have been removed. See attachment: translator_fr-2001-07-24.zip

 - A question:

I have a question about trRTFansicp() and 
trRTFCharSet(). I don't know what to put.

RTF maintainers could help me maybe?

Here are the only things I know:

ISO 8859-1 aka Latin-1 is available for French
but without œ. For a complet French set,
it's possible to use ISO 8859-15 aka Latin-9 or
Latin-0.

Concerning unicode, the scripts to be used for
French are from Basic Latin plus Latin-1 Supplement
plus Latin Extended-A corresponding to the ranges
[0-127] plus [126-255] plus [256-383]


Greetings,

Xavier.

--
 D2SET non profit association
  http://www.d2set.org
  mailto:d2...@d2...

 Artificial Anthill Project
  http://www.aanthill.org/
  mailto:aan...@aa...

[Doxygen-develop] Transparent HTML entities: files

[Xavier O. <xav...@an...>]

John Olsson wrote:

> [...]> Sorry for newbie questions. I just wanted to help a little (for my
> needs

> > first), I'm simply maintainer of the French location of Doxygen. :-)
> > [...]
> >
> Aren't we all newbies? ;)

I think I'm the newest one. ;-)

> [...]
> Also, the default behaviour of flex is to print everything it can't match
> to stdout (this is the default rule which is always active). However, the
> flex code in doc.l (and scanner.l) has defined a rule which overrides the
> default rule which silently ignores text it can't match. If you modify the
> "match-all" rule so it looks like this
>
> <*>.                                    { ECHO; }
>
> you will "restore" the default behaviour (I think).

I don't know the reason why it is such. I'm not sure 'restoring' would
be a good idea. I prefer to restrict to entities in the form &entity;.

So here are my changes in sources. Files modified are:
 outputgen.h // new method writeEntity(const char* const entity) = 0;
or writeEntity(const char* const entity, int length) = 0; depending if
char* yytext has a trailing \0 or not, cf my PS.
 outputlist.h
 mangen.h    // empty implementation
 latexgen.h    // empty implementation
 rtfgen.h        // empty implementation
 html.h        // tranparent entities for HMTL
 doc.l    // new match for all entities

In all files writeEntity() is just behind writeCCedil().

Sorry, I have not time to compile and so on (I'm not under Linux :( ).
Tell me if there is any bug. I will try to implement the method for
LatexGenerator if I have free time. In any case, I will not implement
nothing for ManGenerator and RTFGenerator

Greetings,

Xavier.

PS: Because I don't know if yytext ends with '\0',
I include 2 zip:
-1 transparent-SGML-entities-no length parameter.zip
     To be used if yytext does _not_ include trailing '\0'.
     strlen(yytext) cannot be used.
-2 transparent-SGML-entities-no length parameter.zip
     To be used if yytext does include trailing '\0'.
     strlen(yytext) can be used
OK, I could read flex doc but that is faster. Hope you will
not quarrel me about that. :)

Re: [Doxygen-develop] Adding of new (all) HTML entities? A oneline solution?

[John O. <jo...@ly...>]

>  -1 In the regex, there is [a-zA-Z0-9]{$} where $ is 1,2,3 or 4.
>       I think this means repeat $ times an alphanumeric value.
>       (I'm using Regular Expression syntax of Python 1.5, I hope
>       that's the sames rules Doxygen uses).
>
It is the regexp rules of flex you are using. Read the man-page for flex
for the full documentation of the regexp syntax available. Here is a short
snippet

PATTERNS
     The patterns in the input are written using an extended  set
     of regular expressions.  These are:

         x          match the character 'x'
         .          any character (byte) except newline
         [xyz]      a "character class"; in this case, the pattern
                      matches either an 'x', a 'y', or a 'z'
         [abj-oZ]   a "character class" with a range in it; matches
                      an 'a', a 'b', any letter from 'j' through 'o',
                      or a 'Z'
         [^A-Z]     a "negated character class", i.e., any character
                      but those in the class.  In this case, any
                      character EXCEPT an uppercase letter.
         [^A-Z\n]   any character EXCEPT an uppercase letter or
                      a newline
         r*         zero or more r's, where r is any regular expression
         r+         one or more r's
         r?         zero or one r's (that is, "an optional r")
         r{2,5}     anywhere from two to five r's
         r{2,}      two or more r's
         r{4}       exactly 4 r's
         {name}     the expansion of the "name" definition
                    (see above)
         "[xyz]\"foo"
                    the literal string: [xyz]"foo
         \X         if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v',
                      then the ANSI-C interpretation of \x.
                      Otherwise, a literal 'X' (used to escape
                      operators such as '*')
         \0         a NUL character (ASCII code 0)
         \123       the character with octal value 123
         \x2a       the character with hexadecimal value 2a
         (r)        match an r; parentheses are used to override
                      precedence (see below)

(this is only a part of the regular expressions available)

But I think that you can use the {$} syntax if I understand the above text
correctly. :)


> By longest matching, you certainly means the more restrictive, the more
> precise. So I think this will work.I will provide changes soon.
> 
Yes. :)


> Sorry for newbie questions. I just wanted to help a little (for my needs
> first), I'm simply maintainer of the French location of Doxygen. :-)
> [...]
> 
Aren't we all newbies? ;)

If you add the '-r' switch to flex when it generates the C-source code it
will insert debug printouts, giving verbose information about what happens
when it parses the text.

Also, the default behaviour of flex is to print everything it can't match
to stdout (this is the default rule which is always active). However, the
flex code in doc.l (and scanner.l) has defined a rule which overrides the
default rule which silently ignores text it can't match. If you modify the
"match-all" rule so it looks like this

<*>.                                    { ECHO; }

you will "restore" the default behaviour (I think).


/John

[Doxygen-develop] (i18n) Notice for doxygen language maintainers

[Prikryl,Petr <PRI...@sk...>]

Hi,

As new CVS version of doxygen was released by Dimitri (20010723),
I would like to remind all the language maintainers the changes of the
TranslatorXxxx classes design and what are the consequences
and advantages for you as for the language maintainers.

The primary purpose of the design changes was to make the maintenance
of languages less dependent on the doxygen core development.  Using
translator-adapter classes helps to introduce changes of the Translator
class interface used by the core.  (The translator adapter classed appeared
firstly in 1.2.6-xxxx CVS version and in the official release 1.2.7.)

The second goal was to make the language maintenance easier and
the status of the language support more visible.  The translator adapter
classes were designed so, that it is possible to extract the information
about when your language support was last updated (i.e. version of 
doxygen).

Please, try to update your language.  Users will be happy.  If you do not
have time to update it (everyone will understand that you may have
good reasons for not having time), let it know publicly and try to search
for another language maintainer.

You should read http://www.stack.nl/~dimitri/doxygen/langhowto.html
document which is now generated from sources and document templates.
It contains the table that shows the status (doxygen version) of your
language
support.  It also contains new information about "How to add new language
to doxygen" and "How to maintain a language".  The later is probably
more important for you.  It explains how things with translator adapter
classes
work and recommends what you should do to update your TranslatorXxxx class.

(Note, that you may get newer version of the documentation when you
generate the documentation from your own souces.  Dimitri may have reasons
not to update the on-line documentation for each CVS release ;-)

Notice: if your TranslatorXxxx class is very old (a lot of things changed), 
you may prefer to implement it from scratch (by copying the
TranslatorEnglish
and translating the texts again).  This could be the case of the language 
support last updated for doxygen 1.0.x or 1.1.x.

If in doubt what some of the methods should do, have a look at the
translator_en.h
which (by definition) is always up-to-date, and which contains fresh
comments.

The translator.pl was created to help you with maintenance.  It is called
automatically when the doxygen documentation is generated
(doxygen/doc/Makefile).
You can also run it manually (doxygen/doc/translator.pl).  The Windows users
may use the doxygen/doc/translator.bat for running the script. Perl of 5.005
or higher version is required.

The translator.pl basically helps to generate doxygen's documentation 
(the language.doc file). But, for the language maintainers, it generates
also 
the translator_report.txt ASCII file.

ATTENTION!

The doxygen/doc/translator_report.txt contains some information that cannot
be found on other places.  Being the language maintainer, you should not
stop to
read it as soon as you see that your translator is up-to-date.  The file may
still list
some details for your translator class below.

The most usual case is that the up-to-date translator still contains 
the implementation of methods that are not used by the doxygen core any
more.
They are marked as obsolete methods, and the code should be removed from
your translator_xx.h (it is never used).

Note, that the translator_report.txt is generated automatically from source.
If you find something wrong in it, please, let me know.

Here is the content of the translator_report.txt file -- generated from 
doxygen 1.2.8-20010723.

With regards,
  Petr

=============================================================
Doxygen supports the following (24) languages (sorted alphabetically):

  Brazilian
  Chinese
  Croatian
  Czech
  Danish
  Dutch
  English
  Finnish
  French
  German
  Hungarian
  Italian
  Japanese
  Korean
  Norwegian
  Polish
  Portuguese
  Romanian
  Russian
  Slovak
  Slovene
  Spanish
  Swedish
  Ukrainian

----------------------------------------------------------------------
The following translator classes are up-to-date (sorted alphabetically).
This means that they derive from the Translator class.  If the translator
derives from TranslatorAdapterCVS, it is considered to be almost up-to-date.
In other words, it is newer than the last official release.  Anyway, there
still may be some details listed even for the up-to-date translators.
Please, check the text below.

  TranslatorBrazilian
  TranslatorCroatian
  TranslatorCzech
  TranslatorDutch
  TranslatorEnglish
  TranslatorFrench
  TranslatorGerman
  TranslatorPortuguese
  TranslatorRussian
  TranslatorUkrainian

----------------------------------------------------------------------
The following translator classes are obsolete (sorted alphabetically).
This means that they derive from some of the adapter classes.

  TranslatorChinese     (TranslatorAdapter_1_2_1)
  TranslatorDanish      (TranslatorAdapter_1_2_7)
  TranslatorFinnish     (TranslatorAdapter_1_0_0)
  TranslatorHungarian   (TranslatorAdapter_1_2_1)
  TranslatorItalian     (TranslatorAdapter_1_2_7)
  TranslatorJapanese    (TranslatorAdapter_1_2_5)
  TranslatorKorean      (TranslatorAdapter_1_1_0)
  TranslatorNorwegian   (TranslatorAdapter_1_2_2)
  TranslatorPolish      (TranslatorAdapter_1_2_1)
  TranslatorRomanian    (TranslatorAdapter_1_2_1)
  TranslatorSlovak      (TranslatorAdapter_1_2_7)
  TranslatorSlovene     (TranslatorAdapter_1_1_5)
  TranslatorSpanish     (TranslatorAdapter_1_2_7)
  TranslatorSwedish     (TranslatorAdapter_1_0_0)


----------------------------------------------------------------------
Localized translators are expected to implement the following methods
(prototypes sorted aplhabetically):

QCString idLanguage()
QCString idLanguageCharset()
QCString latexLanguageSupportCommand()
QCString trAlphabeticalList()
QCString trAttention()
QCString trAuthor(bool first_capital, bool singular)
QCString trBug()
QCString trBugList()
QCString trBugsAndLimitations()
QCString trClass(bool first_capital, bool singular)
QCString trClassDiagram(const char *clName)
QCString trClassDocumentation()
QCString trClassHierarchy()
QCString trClassHierarchyDescription()
QCString trClasses()
QCString trCode()
QCString trCollaborationDiagram(const char *clName)
QCString trCompoundIndex()
QCString trCompoundList()
QCString trCompoundListDescription()
QCString trCompoundMembers()
QCString trCompoundMembersDescription(bool extractAll)
QCString trCompoundReference(const char *clName, ClassDef::CompoundType
compType, bool isTemplate)
QCString trCompounds()
QCString trConstructorDocumentation()
QCString trDCOPMethods()
QCString trDate()
QCString trDefineDocumentation()
QCString trDefineValue()
QCString trDefinedAtLineInSourceFile()
QCString trDefinedIn()
QCString trDefinedInSourceFile()
QCString trDefines()
QCString trDeprecated()
QCString trDetailedDescription()
QCString trDocumentation()
QCString trEnumName()
QCString trEnumValue()
QCString trEnumerationTypeDocumentation()
QCString trEnumerationValueDocumentation()
QCString trEnumerationValues()
QCString trEnumerations()
QCString trExampleDocumentation()
QCString trExamples()
QCString trExamplesDescription()
QCString trExceptions()
QCString trField(bool first_capital, bool singular)
QCString trFile(bool first_capital, bool singular)
QCString trFileDocumentation()
QCString trFileIndex()
QCString trFileList()
QCString trFileListDescription(bool extractAll)
QCString trFileMembers()
QCString trFileMembersDescription(bool extractAll)
QCString trFileReference(const char *fileName)
QCString trForInternalUseOnly()
QCString trFriends()
QCString trFuncProtos()
QCString trFunctionDocumentation()
QCString trFunctionPrototypeDocumentation()
QCString trFunctions()
QCString trGeneratedAt(const char *date,const char *projName)
QCString trGeneratedAutomatically(const char *s)
QCString trGeneratedBy()
QCString trGeneratedFromFiles(ClassDef::CompoundType compType, bool single)
QCString trGlobal(bool first_capital, bool singular)
QCString trGotoDocumentation()
QCString trGotoGraphicalHierarchy()
QCString trGotoSourceCode()
QCString trGotoTextualHierarchy()
QCString trGraphicalHierarchy()
QCString trGroup(bool first_capital, bool singular)
QCString trHeaderFiles()
QCString trHeaderFilesDescription()
QCString trHierarchicalIndex()
QCString trInclByDepGraph()
QCString trInclDepGraph(const char *fName)
QCString trIncludingInheritedMembers()
QCString trInheritedByList(int numEntries)
QCString trInheritsList(int numEntries)
QCString trInitialValue()
QCString trInterfaces()
QCString trInvariant()
QCString trLegend()
QCString trLegendDocs()
QCString trLegendTitle()
QCString trListOfAllMembers()
QCString trMainPage()
QCString trMember(bool first_capital, bool singular)
QCString trMemberDataDocumentation()
QCString trMemberEnumerationDocumentation()
QCString trMemberFunctionDocumentation()
QCString trMemberList()
QCString trMemberTypedefDocumentation()
QCString trModuleDocumentation()
QCString trModuleIndex()
QCString trModules()
QCString trModulesDescription()
QCString trMore()
QCString trNamespace(bool first_capital, bool singular)
QCString trNamespaceDocumentation()
QCString trNamespaceIndex()
QCString trNamespaceList()
QCString trNamespaceListDescription(bool extractAll)
QCString trNamespaceMemberDescription(bool extractAll)
QCString trNamespaceMembers()
QCString trNamespaceReference(const char *namespaceName)
QCString trNamespaces()
QCString trNoDescriptionAvailable()
QCString trNote()
QCString trPackage(const char *name)
QCString trPackageDocumentation()
QCString trPackageList()
QCString trPackageListDescription()
QCString trPackages()
QCString trPage(bool first_capital, bool singular)
QCString trPageAbbreviation()
QCString trPageDocumentation()
QCString trPageIndex()
QCString trParameters()
QCString trPostcondition()
QCString trPrecondition()
QCString trPrivateAttribs()
QCString trPrivateMembers()
QCString trPrivateSlots()
QCString trPrivateTypes()
QCString trProperties()
QCString trPropertyDocumentation()
QCString trProtectedAttribs()
QCString trProtectedMembers()
QCString trProtectedSlots()
QCString trProtectedTypes()
QCString trPublicAttribs()
QCString trPublicMembers()
QCString trPublicSlots()
QCString trPublicTypes()
QCString trRTFCharSet()
QCString trRTFGeneralIndex()
QCString trRTFansicp()
QCString trReferenceManual()
QCString trReferencedBy()
QCString trReimplementedForInternalReasons()
QCString trReimplementedFromList(int numEntries)
QCString trReimplementedInList(int numEntries)
QCString trRelatedFunctionDocumentation()
QCString trRelatedFunctions()
QCString trRelatedPages()
QCString trRelatedPagesDescription()
QCString trRelatedSubscript()
QCString trRemarks()
QCString trReturnValues()
QCString trReturns()
QCString trSearch()
QCString trSeeAlso()
QCString trSignals()
QCString trSince()
QCString trSources()
QCString trStaticPrivateAttribs()
QCString trStaticPrivateMembers()
QCString trStaticProtectedAttribs()
QCString trStaticProtectedMembers()
QCString trStaticPublicAttribs()
QCString trStaticPublicMembers()
QCString trTest()
QCString trTestList()
QCString trThisIsTheListOfAllMembers()
QCString trTodo()
QCString trTodoList()
QCString trTypedefDocumentation()
QCString trTypedefs()
QCString trVariableDocumentation()
QCString trVariables()
QCString trVersion()
QCString trWarning()
QCString trWriteList(int numEntries)
QCString trWrittenBy()


======================================================================
Details related to specific translator classes follow.



TranslatorBrazilian (Translator)
-------------------

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorChinese (TranslatorAdapter_1_2_1)
-----------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorDanish (TranslatorAdapter_1_2_7)
----------------

Missing methods (should be implemented):

  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString trAuthor()
  QCString trAuthors()



TranslatorSpanish (TranslatorAdapter_1_2_7)
-----------------

Missing methods (should be implemented):

  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorFinnish (TranslatorAdapter_1_0_0)
-----------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString idLanguageCharset()
  QCString trNamespaces()
  QCString trGeneratedFromFiles(ClassDef::CompoundType compType, bool
single)
  QCString trAlphabeticalList()
  QCString trReturnValues()
  QCString trMainPage()
  QCString trPageAbbreviation()
  QCString trSources()
  QCString trDefinedAtLineInSourceFile()
  QCString trDefinedInSourceFile()
  QCString trDeprecated()
  QCString trCollaborationDiagram(const char *clName)
  QCString trInclDepGraph(const char *fName)
  QCString trConstructorDocumentation()
  QCString trGotoSourceCode()
  QCString trGotoDocumentation()
  QCString trPrecondition()
  QCString trPostcondition()
  QCString trInvariant()
  QCString trInitialValue()
  QCString trCode()
  QCString trGraphicalHierarchy()
  QCString trGotoGraphicalHierarchy()
  QCString trGotoTextualHierarchy()
  QCString trPageIndex()
  QCString trNote()
  QCString trPublicTypes()
  QCString trPublicAttribs()
  QCString trStaticPublicAttribs()
  QCString trProtectedTypes()
  QCString trProtectedAttribs()
  QCString trStaticProtectedAttribs()
  QCString trPrivateTypes()
  QCString trPrivateAttribs()
  QCString trStaticPrivateAttribs()
  QCString trTodo()
  QCString trTodoList()
  QCString trReferencedBy()
  QCString trRemarks()
  QCString trAttention()
  QCString trInclByDepGraph()
  QCString trSince()
  QCString trLegendTitle()
  QCString trLegendDocs()
  QCString trLegend()
  QCString trTest()
  QCString trTestList()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trGeneratedFrom(const char *s,bool single)
  QCString trVerbatimText(const char *f)



TranslatorFrench (Translator)
----------------

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trIncludeFile()
  QCString trVerbatimText(const char *f)



TranslatorHungarian (TranslatorAdapter_1_2_1)
-------------------

Missing methods (should be implemented):

  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorItalian (TranslatorAdapter_1_2_7)
-----------------

Missing methods (should be implemented):

  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorJapanese (TranslatorAdapter_1_2_5)
------------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorKorean (TranslatorAdapter_1_1_0)
----------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString trNote()
  QCString trPublicTypes()
  QCString trPublicAttribs()
  QCString trStaticPublicAttribs()
  QCString trProtectedTypes()
  QCString trProtectedAttribs()
  QCString trStaticProtectedAttribs()
  QCString trPrivateTypes()
  QCString trPrivateAttribs()
  QCString trStaticPrivateAttribs()
  QCString trTodo()
  QCString trTodoList()
  QCString trReferencedBy()
  QCString trRemarks()
  QCString trAttention()
  QCString trInclByDepGraph()
  QCString trSince()
  QCString trLegendTitle()
  QCString trLegendDocs()
  QCString trLegend()
  QCString trTest()
  QCString trTestList()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorNorwegian (TranslatorAdapter_1_2_2)
-------------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString idLanguageCharset()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorPolish (TranslatorAdapter_1_2_1)
----------------

Missing methods (should be implemented):

  QCString idLanguageCharset()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorPortuguese (Translator)
--------------------

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()



TranslatorRomanian (TranslatorAdapter_1_2_1)
------------------

Missing methods (should be implemented):

  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorSwedish (TranslatorAdapter_1_0_0)
-----------------

Missing methods (should be implemented):

  QCString latexLanguageSupportCommand()
  QCString idLanguageCharset()
  QCString trDeprecated()
  QCString trCollaborationDiagram(const char *clName)
  QCString trInclDepGraph(const char *fName)
  QCString trConstructorDocumentation()
  QCString trGotoSourceCode()
  QCString trGotoDocumentation()
  QCString trPrecondition()
  QCString trPostcondition()
  QCString trInvariant()
  QCString trInitialValue()
  QCString trCode()
  QCString trGraphicalHierarchy()
  QCString trGotoGraphicalHierarchy()
  QCString trGotoTextualHierarchy()
  QCString trPageIndex()
  QCString trNote()
  QCString trPublicTypes()
  QCString trPublicAttribs()
  QCString trStaticPublicAttribs()
  QCString trProtectedTypes()
  QCString trProtectedAttribs()
  QCString trStaticProtectedAttribs()
  QCString trPrivateTypes()
  QCString trPrivateAttribs()
  QCString trStaticPrivateAttribs()
  QCString trTodo()
  QCString trTodoList()
  QCString trReferencedBy()
  QCString trRemarks()
  QCString trAttention()
  QCString trInclByDepGraph()
  QCString trSince()
  QCString trLegendTitle()
  QCString trLegendDocs()
  QCString trLegend()
  QCString trTest()
  QCString trTestList()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorSlovene (TranslatorAdapter_1_1_5)
-----------------

Missing methods (should be implemented):

  QCString trLegendTitle()
  QCString trLegendDocs()
  QCString trLegend()
  QCString trTest()
  QCString trTestList()
  QCString trDCOPMethods()
  QCString trProperties()
  QCString trPropertyDocumentation()
  QCString trInterfaces()
  QCString trClasses()
  QCString trPackage(const char *name)
  QCString trPackageList()
  QCString trPackageListDescription()
  QCString trPackages()
  QCString trPackageDocumentation()
  QCString trDefineValue()
  QCString trBug()
  QCString trBugList()
  QCString trRTFansicp()
  QCString trRTFCharSet()
  QCString trRTFGeneralIndex()
  QCString trClass(bool first_capital, bool singular)
  QCString trFile(bool first_capital, bool singular)
  QCString trNamespace(bool first_capital, bool singular)
  QCString trGroup(bool first_capital, bool singular)
  QCString trPage(bool first_capital, bool singular)
  QCString trMember(bool first_capital, bool singular)
  QCString trField(bool first_capital, bool singular)
  QCString trGlobal(bool first_capital, bool singular)
  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString latexBabelPackage()
  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()
  QCString trVerbatimText(const char *f)



TranslatorSlovak (TranslatorAdapter_1_2_7)
----------------

Missing methods (should be implemented):

  QCString trAuthor(bool first_capital, bool singular)

Obsolete methods (should be removed):

  QCString trAuthor()
  QCString trAuthors()
  QCString trFiles()

=======================================================


-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

Re: [Doxygen-develop] Adding of new (all) HTML entities? A oneline solution?

[Xavier O. <xav...@an...>]

John Olsson wrote:

> > doc.l would be modify and this line added:
> > <DocScan,Text>"&"[a-zA-Z0-9]{1}";"   { outDoc->writeEntity(yytext[1]); }
> > <DocScan,Text>"&"[a-zA-Z0-9]{2}";"   { outDoc->writeEntity(yytext[2]); }
> > <DocScan,Text>"&"[a-zA-Z0-9]{3}";"   { outDoc->writeEntity(yytext[3]); }
> > <DocScan,Text>"&"[a-zA-Z0-9]{4}";"   { outDoc->writeEntity(yytext[4]); }
> >
> > I have several questions...:
> >
> >  -Q1: Are the following single line could replace the 4 lines?
> > <DocScan,Text>"&"[a-zA-Z0-9]{1,4}";"   { outDoc->writeEntity(yytext[4]); }
> > (I'm very lazy! :-)
> >
> Why do you have yytext[1] etc. in the above example and only yytext[4] in
> your suggested replacement?

 -1 In the regex, there is [a-zA-Z0-9]{$} where $ is 1,2,3 or 4.
      I think this means repeat $ times an alphanumeric value.
      (I'm using Regular Expression syntax of Python 1.5, I hope
      that's the sames rules Doxygen uses).
 -2 I have supposed that yytext[1] means one character, yytext[2] ,...
     But it means, the second character, the third and so on
     It was alos not correct because &alpha; has more than 4 characters!
     I ha in mind numeric entities like &#1245;. Well ...

So now, I think that it would be more correct to have:
<DocScan,Text>"&"[a-zA-Z0-9]{1,}";"   { outDoc->writeEntity(yytext,strlen(yytext));
}

void HtmlGenerator::writeEntity(const char* const text, int length)
{
  if (text)
  {
    char c;
    int textlength = length;
    while (textlength)
    {
      c=*text++;
      t << c;
      textlength--;
    }
  }
}

> > -Q2:  There is a theorical problem: what is the order of scanning? to be
> >          backward compatible, the added regex should be check if nothing
> >          else has already matched.
> >
> If you read the flex manual page everything will be explained. ;)
>
> The parser generated by flex picks the longest matching rule it can find
> of all active rules. One way for a rule to become active is to call for it
> explicitly, i.e. BEGIN(DocScan) will activate all rules with DocScan in
> them.

By longest matching, you certainly means the more restrictive, the more
precise. So I think this will work.I will provide changes soon.

Sorry for newbie questions. I just wanted to help a little (for my needs
first), I'm simply maintainer of the French location of Doxygen. :-)
[...]

Thanks,

Xavier.
--
 Artificial Anthill Project
  http://www.aanthill.org/
  mailto:aan...@aa...

 D2SET Non Profit Association
  http://www.d2set.org/
  mailto:d2...@d2...

Re: [Doxygen-develop] Bug in RTF Output in Doxygen 1.2.8.1

[Rene L. <rl...@ko...>]

Hauke Jans wrote:

>         Dear Doxygen Fans!
>
> I tried version 1.2.8.1 of doxygen
> and noticed a minor glitch:
>
> In this version the gifs in the rtf
> output are missing.
>
> When looking at the rtf in
> word, i noticed that in Version 1.2.6
>
> EINF=DCGENGRAFIK class_CWapResult_coll_graph.gif \*FORMATVERBINDEN
>
> was inserted, while in 1.2.8.1
>
> EINF=DCGENGRAFIK classCWapResult_coll_graph.gif \*FORMATVERBINDEN
>
> was inserted.
>
> A colleauge tried the following patch, but
> i did not tested it. He had the same problem
> and reportet that the patch worked.
>
> --- rtfgen.cpp.orig     Fri Jul 20 13:39:02 2001
> +++ rtfgen.cpp  Thu Jul 19 19:14:18 2001
> @@ -2547,7 +2547,7 @@
>    t << "{" << endl;
>    t << Rtf_Style_Reset << endl;
>    t << "\\par\\pard \\qc {\\field\\flddirty {\\*\\fldinst
> INCLUDEPICTURE ";
> -  t << g.diskName() << ".gif";
> +  t << convertNameToFile(g.diskName()) << ".gif";
>    t << " \\\\*MERGEFORMAT}{\\fldrslt IMAGE}}\\par" << endl;
>    t << "}" << endl;
>  }
>
>         Greetings
>
>                 Hauke Jans
>
> --
> S.E.S.A. Software und Systeme AG
> Hauke Jans
> Stolberger Stra=DFe 374
> D-50933 K=F6ln
> Phone +49 (0)221/485-1160
> Fax   +49 (0)221/485-1170
> Email hau...@ko...
> WWW   www.sesa.de
>
>   ---------------------------------------------------------------------=
---
>                  Name: hcj.vcf
>    hcj.vcf       Type: VCard (text/x-vcard)
>              Encoding: quoted-printable
>           Description: Card for Hauke Jans

Hello,

I am the college and just send a better patch.

Thanks
Ren=E9

[Doxygen-develop] Bug #440393

[Rene L. <rl...@ko...>]

I've attached a patch for Bug #440393

thanks,
Ren=E9

[Doxygen-develop] Bug in RTF Output in Doxygen 1.2.8.1

[Hauke J. <hc...@ko...>]

	Dear Doxygen Fans!


I tried version 1.2.8.1 of doxygen
and noticed a minor glitch:

In this version the gifs in the rtf
output are missing.

When looking at the rtf in
word, i noticed that in Version 1.2.6

EINF=DCGENGRAFIK class_CWapResult_coll_graph.gif \*FORMATVERBINDEN

was inserted, while in 1.2.8.1


EINF=DCGENGRAFIK classCWapResult_coll_graph.gif \*FORMATVERBINDEN

was inserted.

A colleauge tried the following patch, but
i did not tested it. He had the same problem
and reportet that the patch worked.


--- rtfgen.cpp.orig     Fri Jul 20 13:39:02 2001
+++ rtfgen.cpp  Thu Jul 19 19:14:18 2001
@@ -2547,7 +2547,7 @@
   t << "{" << endl;
   t << Rtf_Style_Reset << endl;
   t << "\\par\\pard \\qc {\\field\\flddirty {\\*\\fldinst
INCLUDEPICTURE ";
-  t << g.diskName() << ".gif";
+  t << convertNameToFile(g.diskName()) << ".gif";
   t << " \\\\*MERGEFORMAT}{\\fldrslt IMAGE}}\\par" << endl;
   t << "}" << endl;
 }




        Greetings

                Hauke Jans



--=20
S.E.S.A. Software und Systeme AG
Hauke Jans
Stolberger Stra=DFe 374
D-50933 K=F6ln
Phone +49 (0)221/485-1160
Fax   +49 (0)221/485-1170
Email hau...@ko...
WWW   www.sesa.de

[Doxygen-develop] Re: Customizing look in Doxygen

[joe b. <be...@mc...>]

I've attached the patch I mentioned in an earlier mail to doxygen-users.
It basically reformats the function return values, name, and parameters
in the detailed description for html pages, so that they are more
vertically oriented, like the following:

return specifier
function name(
    parameter type           parameter name,
    ...)

The old rendering is currently just #if'd out, so you can see what my
changes are doing. It would be great if this could be either the
default or an optional configuration-option controlled layout for the 
html output of doxygen.

thanks,
joe

Re: [Doxygen-develop] Adding of new (all) HTML entities? A one line solution?

[John O. <jo...@ly...>]

> doc.l would be modify and this line added:
> <DocScan,Text>"&"[a-zA-Z0-9]{1}";"   { outDoc->writeEntity(yytext[1]); }
> <DocScan,Text>"&"[a-zA-Z0-9]{2}";"   { outDoc->writeEntity(yytext[2]); }
> <DocScan,Text>"&"[a-zA-Z0-9]{3}";"   { outDoc->writeEntity(yytext[3]); }
> <DocScan,Text>"&"[a-zA-Z0-9]{4}";"   { outDoc->writeEntity(yytext[4]); }
> 
> I have several questions...:
> 
>  -Q1: Are the following single line could replace the 4 lines?
> <DocScan,Text>"&"[a-zA-Z0-9]{1,4}";"   { outDoc->writeEntity(yytext[4]); }
> (I'm very lazy! :-)
>
Why do you have yytext[1] etc. in the above example and only yytext[4] in
your suggested replacement?


> -Q2:  There is a theorical problem: what is the order of scanning? to be
>          backward compatible, the added regex should be check if nothing
>          else has already matched.
>
If you read the flex manual page everything will be explained. ;)

The parser generated by flex picks the longest matching rule it can find
of all active rules. One way for a rule to become active is to call for it
explicitly, i.e. BEGIN(DocScan) will activate all rules with DocScan in
them.


BTW. I have now successfully implemented my tags so that I can write

@run foo @filename bar gazonk @endrun

*and*

@file @run foo @filename bar gazonk @endrun

I had to modify (among other things) the function findFileDef found in
util.cpp so that it recognizes ClearCase version numbers. The command

@run cleartool ls @filename @endrun

would result in something like this

/view/r10_epkjols_garp/vobs/bscrp/r10_new_trh/foo.c@@/main/r10_predev/CHECKEDOUT
from /main/r10_predev/1                 Rule: CHECKEDOUT

beeing returned from cleartool (in the case when a file is checked out).
My changes makes the findFileDef function aware of the @-signes in the
string and when comparing against already found files it ignores
everything after the first @-sign (including the sign itself). I have also
added a new method to the FileDef class called setVersion() which stores a
QCString containing version number infomration about the file, i.e. in my
case everything after the @-signes including them as well.

Then in the writeDocumentation() method in FileDef I modified the title
etc. to use my getVersionName() method which returns the filename combined
with version infomration.

I have also modified the layout of the generated HTML-pages so the result
looks more like what Java2 JavaDoc outputs. The reason for doing so was
simply that when you have code containing several pages of #define
statements and (in the same file) several pages of functions it is very
difficult to see where the different sections start and end. IMHO the
Java2 way of solving this by using lightblue background for the headings
solves this problem nicely.

When doing these changes to the layout I found out that the pages
containing the lists of todo:s, bug:s and test:s uses a different to
generate the headings. They use startSection() instead of startTitle().

Is this a bug, and if not, what is the design reason for doing it that
way?

As a result of changing the layout, I came quickly to the conclusion that
the layout of the generated files should not be hardcoded. Instead I think
that a user should be able to configure this via external file(s). One
possibility would be to have the document layout of the different kinds of
pages defined using XML. That is (for example), instead of having
configuration options for which of the different dot-diagrams I want to 
have, I modify an XML file. Just to give you an idea of what I'am after
I'll give you an example of what such a file could look like


<sourcecode>
  <tagDefinitions>
    <define heading>
     <before data="<table border=1 cellpadding=3 cellspacing=0 width=100%>
                    <tr bgcolor=#CCCCFF>
                     <td colspan=1><font size=+2><b>"/>
     <after data="   </b></font></td>
                    </tr>
                   </table><br>"
    </define>
    <define include>
     <before data="<code>"/>
     <after data="</code><br>"/>
    </define>

    etc.
  </tagDefinitions>

  <layout>
    <tag name="heading">
    <tag name="include">
    
    etc.
  </layout>
</sourcecode>


If a user wants the include section repeated in the detailed section, you
do not have to modify the source code, just modify the layout section in
the XML file. The same goes if you want your headings in some other way
than the default provided etc. etc.

Ofcourse you have to have different layouts for the different targets
(HTML, LaTeX, man, RTF, ...), but you can never avoid that. The question
is if that information should be hardcoded or not...


/John

Re: [Doxygen-develop] Doxygen and XML...

[Dimitri v. H. <di...@st...>]

On Mon, Jul 23, 2001 at 02:34:33PM +0200, Prikryl,Petr wrote:
> Dimitri wrote...
> > 
> > I see XML output as an intermediate interface, that would allow
> > several front-ends to produce specific output (e.g. html output or
> > something very different like code metrics). The XML output would
> > contain all information, the front-ends will then pick the appropriate
> > information and transform that into the actual output.
> 
> The more I think about it, the more I also incline towards internal
> XML DTD (say doxygen internal XML).

For the moment I even plan to drop DTD's altogether for the internal XML. 
The reasons: 
1) The output is not very fixed at the moment, so maintaining a consistent DTD
   is more work. 
2) DTD's are to be replaced by schemas (see http://www.w3.org/TR/xmlschema-0/) 
   in the future (at least that is what W3C would like to see). 
3) DTD's are difficult to read and do not have that much expressive power.

> > In theory there are plenty of XML tools that can transform XML output
> > into something else. In practice these tools are just not there (at
> > least I haven't seen them). All that there really is, is an easy way to
> > parse XML and build up the structure contained in an XML file into
> > structures in memory. So the plan is to provide a C++/Qt based XML 
> > parser that understands doxygen's XML output. People that wish to
> > add support for another output format can do so by using the structures
> > build up by this parser.
> 
> I am very new to XML, but there are tools used with DocBook XML and
> they are more general than only for supporting DocBook.  This
> requires better analysis.

Ok, let me know what you find.

> 
> > With respect to DocBook format: I have looked at it, but I think it
> > covers only 20% of what doxygen will produce. So any docbook tool
> > (which are currently all SGML based by the way), wouldn't be very
> > useful.
> 
> I am not sure (just starting with DocBook), but I think that DocBook
> is much richer that say HTML or LaTeX and it is very suitable for
> producing the end documents.  It may not fit to be used as
> the internal XML format, but I would see it as the main final output
> format.  Let's think about the following approach:
> 
>   input sources
>    |
>    +--> doxygen internal XML (by doxygen parsers)
>            |
>            +--> DocBook XML
>            |      |
>            |      +--> HTML
>            |      +--> RTF
>            |      +--> jadetex --> DVI, PDF, PS
>            |      +--> etc.
>            |
>            +--> some other postprocessing of the internal doxygen XML

Yes, this is the way I see it as well. DocBook XML is just one
(but a generic) output format. I think HTML and LaTeX would still be
better off with a direct front-end. See below why.

> 
> The important thing to note is that DocBook is not exclusively SGML
> based.  While this could be the truth in the past, majority of
> DocBook users probably uses DocBook XML these days.  Norman Walsh,
> one of the DocBook leaders also considers the XML be the future of
> DocBook.  I suggest to focus on DocBook XML exclusively (instead of
> thinking about DocBook SGML).
> 
> What should be clarified is the mentioned 20% coverage of doxygen's
> problems by DocBook.

The 20% is for the internal XML format.

All the structure information that doxygen currently outputs
is not covered by DocBook. Basically only part of the user documentation
blocks and their mark-up is present (things like <para> and <emphasis>
are there, but for instance <bold> is not). Ofcourse DocBook has a lot
more when it comes to formatting a book, but that is all output format
related.

But also for DocBook as the only output format I see problems.
Think for instance about the diagrams that doxygen produces. For HTML these
result in images overlayed with a clickable map. In latex these result in a
vector-based EPS picture. I do not see how to get that result from DocBook
XML.

> > I do not know how these ideas match/conflict with the character 
> > encoding problems mentioned by Petr. Would using XML like this still
> > solve all those problems?
> 
> I guess that yes -- XML will always help to solve the problems.  At
> least, the first parsing phase can be done without problems with
> respect to encoding.  Once having the correctly marked internal XML,
> all problems with languages and encoding become covered by the XML
> standard.

Ok, I trust you that it all will work out nicely :-)

[snip]

> > In summary doxygen would consist of the following:
> > 
> > - the main engine as a library
> > - the xml parser as a library
> > - an extendable configuration parser as a library (contains the
> >   config options for the engine, but can be dynamically extended by the
> >   front-ends to support more options).
> > - a number of front-ends, either as a libraries or as a standalone tools
> > - some glue to make a user friendly tool out of these.
> 
> As far as I understand, the internal XML format will not contain any
> sentences generated by doxygen translators.
> The things like the text around, say, the list of places from where
> the method is called, is not generated into the internal XML.
> Am I right?  I would like to be ;-)

Yes, that is the idea. But ofcourse these sentences have to be somewhere.
With multiple output formats there is the chance of duplication of 
information. So there should still be one place where the translations
of these sentences are defined.

Regards,
  Dimitri

Re: [Doxygen-develop] Adding of new (all) HTML entities? A one line solution?

[Xavier O. <xav...@an...>]

Dimitri van Heesch wrote:

> On Thu, Jul 19, 2001 at 12:37:10PM +0200, Xavier Outhier wrote:
> > Hi,
> >
> >
> > As far as I understand, what is to be done for each new entity
> > is the following:
> >
> > -1 Add a new pure virtual method named writeEntity() in
> >     class BaseOutputDocInterface (outputgen.h)
> > -2 Add a new method
> >     void writeEntity()
> >     { forall(&OutputGenerator::writeEntity); }
> >    in class OutputList (outputlist.h)
> > -3 Add non pure virtual method in generators:
> >     void writeEntity()        {}
> >    in classes
> >     class ManGenerator (mangen.h)
> >     class LatexGenerator (latexgen.h)
> >     class HtmlGenerator (htmlgen.h)
> >
> > Remarks:
> > I do not understand what doc.cpp does really. I suppose it has also
> > to be changed but I don't know how.
>
> doc.cpp is a generated file. Look at the flex file doc.l: You'll see lines like
> these:
>
> <DocScan,Text>"&"[cC]"cedil;"           { outDoc->writeCCedil(yytext[1]); }
>
> these consist of a set of states (between <>), a regular expression,
> and some code.
>
> The code is executed when the input matches the regular expression. yytext
> is a char* containing the actual text that was matched. So the
> above matches &ccedil; and &Ccedil;
>
> > Besides, I know what to do with HTML and LaTeX (maybe not for
> > all symbols, I have to check in my documentation) but I don't know
> > what to do with man.
>
> This has always been a mistery to me too.

The mystery will be thicker now.

> > Questions:
> > Is the process (with the 3 steps) correct? Is something missing?
>
> Seems ok to me.
>
> > As my free time is so precious (as for everybody), is it possible
> > tha I only change the files and send them back for merging,
> > compiling and so on?
>
> Yes, that is fine. You can choose to do only those entities that you
> need as well.

[...]
Until discussion with Petr is not over, I will do it.

I wonder if the work, allowing all entities to be transparent
for Doxygen, could not be done in a straight forward ...
at least for HTML output.

I propose that:
 -1 Add a new method in BaseOutputDocInterface
virtual void writeEntity(const char* const text) = 0;
-2 Add a new method
    void writeEntity()
    { forall(&OutputGenerator::Entity); }
   in class OutputList (outputlist.h)
-3 Add non pure virtual method in generators:
    void writeSpecCharEntity()        {}
   in classes
    class ManGenerator (mangen.h)
    class LatexGenerator (latexgen.h)
    class HtmlGenerator (htmlgen.h)

The straight forwardness is for HTML only (later
intermediate XML):
void HtmlGenerator::writeEntity(const char* const text)
{ t << "&" << text << ";" ;}

doc.l would be modify and this line added:
<DocScan,Text>"&"[a-zA-Z0-9]{1}";"   { outDoc->writeEntity(yytext[1]); }
<DocScan,Text>"&"[a-zA-Z0-9]{2}";"   { outDoc->writeEntity(yytext[2]); }
<DocScan,Text>"&"[a-zA-Z0-9]{3}";"   { outDoc->writeEntity(yytext[3]); }
<DocScan,Text>"&"[a-zA-Z0-9]{4}";"   { outDoc->writeEntity(yytext[4]); }

I have several questions...:

 -Q1: Are the following single line could replace the 4 lines?
<DocScan,Text>"&"[a-zA-Z0-9]{1,4}";"   { outDoc->writeEntity(yytext[4]); }
(I'm very lazy! :-)
-Q2:  There is a theorical problem: what is the order of scanning? to be
         backward compatible, the added regex should be check if nothing
         else has already matched.
-Q3: Could it be all what to do if later Doxygen use XML (DocBook or
        other)? Maybe, we would have to remove all the single entities already
        added?

... and some remarks:
 - R1: If matching order is configurable, then it would solved all HTML
          entities (and SGML, sorry I'm really not a specialist of this domain),
          wouldn't be?
 - R2: For LaTeX, RTF and man (but not XML), more work should be
          done. Is a big switch reasonable in this case? There would be
          255 cases if all entities defined in HTML 4.0 are used.
          But if the current discussion on XML leads to have a runnable version
          in less that 2 or 3 months, it maybe not useful to do that work.
          If it's for longer term (I think it will), then I could begin to do that
          at least for LaTeX.
 - R3: If the "one line" solution is not possible I will only do the changes
          for greek letters (HTML and LaTeX) that could also be useful for
          others.

Waiting the answers to all my questions I will work a little for me. :-)

Xavier.

Doxygen and XML... (was RE: [Doxygen-develop] Adding of new (all) HTML entities?)

[Prikryl,Petr <PRI...@sk...>]

Dimitri wrote
> Xavier wrote
> > Besides, I know what to do with HTML and LaTeX (maybe not for
> > all symbols, I have to check in my documentation) but I don't know
> > what to do with man.
> 
> This has always been a mistery to me too.

Another reason for choosing DocBook XML.  The existing XML tools
can be used to produce man pages (I believe I have read recently
something about that in one of the DocBook mailing lists).

I.e. sources --> internal XML --(alternatively)--> DocBook XML --
transformation XML tools
plus (as other alternatives to the DocBook tool chain) the original 
doxygen's HTML generator,  LaTeX generator, etc.

I feel we are converging!  As I still think that DocBook be 
the good choice, the internal XML should not create 
obstacles.  This is the reason for further analysis.

I have just first touch with DocBook.  I do not have 
good working knowledge.  We should possibly search for
some DocBook experts here.  Do you agree?
Is any DocBook expert reading this? 
(Posted also to doxygen users mailing list for that reason.)

Regards, Petr

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

[Doxygen-develop] Doxygen and XML... (was: Status of XML development? (was Adding o f..))

[Prikryl,Petr <PRI...@sk...>]

Hi,

Dimitri wrote...
> 
> I see XML output as an intermediate interface, that would allow
> several front-ends to produce specific output (e.g. html output or
> something very different like code metrics). The XML output would
> contain all information, the front-ends will then pick the appropriate
> information and transform that into the actual output.

The more I think about it, the more I also incline towards internal
XML DTD (say doxygen internal XML).

> In theory there are plenty of XML tools that can transform XML output
> into something else. In practice these tools are just not there (at
> least I haven't seen them). All that there really is, is an easy way to
> parse XML and build up the structure contained in an XML file into
> structures in memory. So the plan is to provide a C++/Qt based XML 
> parser that understands doxygen's XML output. People that wish to
> add support for another output format can do so by using the structures
> build up by this parser.

I am very new to XML, but there are tools used with DocBook XML and
they are more general than only for supporting DocBook.  This
requires better analysis.

> With respect to DocBook format: I have looked at it, but I think it
> covers only 20% of what doxygen will produce. So any docbook tool
> (which are currently all SGML based by the way), wouldn't be very
> useful.

I am not sure (just starting with DocBook), but I think that DocBook
is much richer that say HTML or LaTeX and it is very suitable for
producing the end documents.  It may not fit to be used as
the internal XML format, but I would see it as the main final output
format.  Let's think about the following approach:

  input sources
   |
   +--> doxygen internal XML (by doxygen parsers)
           |
           +--> DocBook XML
           |      |
           |      +--> HTML
           |      +--> RTF
           |      +--> jadetex --> DVI, PDF, PS
           |      +--> etc.
           |
           +--> some other postprocessing of the internal doxygen XML

The important thing to note is that DocBook is not exclusively SGML
based.  While this could be the truth in the past, majority of
DocBook users probably uses DocBook XML these days.  Norman Walsh,
one of the DocBook leaders also considers the XML be the future of
DocBook.  I suggest to focus on DocBook XML exclusively (instead of
thinking about DocBook SGML).

What should be clarified is the mentioned 20% coverage of doxygen's
problems by DocBook.

> I do not know how these ideas match/conflict with the character 
> encoding problems mentioned by Petr. Would using XML like this still
> solve all those problems?

I guess that yes -- XML will always help to solve the problems.  At
least, the first parsing phase can be done without problems with
respect to encoding.  Once having the correctly marked internal XML,
all problems with languages and encoding become covered by the XML
standard.

What I see as extremely important here is to use correctly the
encoding attribute and the xml:lang attribute. This implies
neccessary splitting the XML output into separate files, at least,
based on the encoding -- if the standard approach was chosen. Here
are the reasons:

 a) If XML document consists of more than one file, one of the files
    is main (contains the DTD identification), the other files are
    read as so called "external entities" (basically &myfile1; is
    expanded as the content, the &myfile1; entity is defined inside
    one separate file).
   
 b) Each xml file implicitly assumes UTF-8 encoding.  If other
    encoding is used, the first line should contain:
   
      <?xml version="1.0" encoding="windows-1250">
   
    for main file or
   
      <?xml encoding="windows-1250">
   
    for the other files (i.e. the external entities).
   
    Then, the rest of the file contains the text encoded in the
    mentioned encoding.
    
    This also means that new Doxyfile option should be used for the
    implicit encoding of the input sources.  And also, new doxygen
    tag should be introduced for explicit marking the file content 
    encoding. This way, it would be possible to process project files
    with different encoding (legacy and OS dependency reasons).
   
 c) The language specific text (i.e. not the encoding specific but
    really things like English, French, Portuguese) can be marked so
    in any element using the xml:lang attribute.  Example (here in <para>
    but this can be inside "any" element):
    
      <chapter xml:lang="en">
      
      <para>Some text in English</para>
      
      <para xml:lang="fr">Bonjour (i.e. some exceptional text in
      French -- excuse mois; I have close to zero knowledge of
      French ;-).</para>
      
      <para xml:lang="ptBR">Brazilian Portuguese</para>
      ...
      </chapter>

    This also means that doxygen could define new tags for marking
    the other language than the base sources (human) language.  
    The Doxyfile should define new option that says what is the
    implicit language of input sources -- possibly INPUT_LANGUAGE.
    This can be (of course) different than the existing
    OUTPUT_LANGUAGE.

The sentences generated by doxygen translators can be produced as
named entities definitions into one file -- this would require
further analysis.  

IMPORTANT: The output could even (possibly) be generated
independently on the languages and the translator could possibly
collapse into one general class.  The internationalization can
possibly be done via language dependent entity rendering via DSSSL
or XSL files (I am not very good here yet.  But at least for DSSSL
it is done in DocBook this way).

I still think that DocBook XML should be the main output to files.
The internal XML coul be so much intermediate that it could exist
only in memory in the form supported by some standard XML library.

For that reason, the internal XML should use DocBook tags if the
tags should not be somehow more special (in the sense to prefer
<para> instead of <p>).

> The nice thing about having an intermediate
> file is that the parser and front-end could also be written in another 
> language such as Python. Furthermore, other input parsers could produce
> the same XML output and benefit from the availble front-ends.
> 
> In summary doxygen would consist of the following:
> 
> - the main engine as a library
> - the xml parser as a library
> - an extendable configuration parser as a library (contains the
>   config options for the engine, but can be dynamically extended by the
>   front-ends to support more options).
> - a number of front-ends, either as a libraries or as a standalone tools
> - some glue to make a user friendly tool out of these.

As far as I understand, the internal XML format will not contain any
sentences generated by doxygen translators.
The things like the text around, say, the list of places from where
the method is called, is not generated into the internal XML.
Am I right?  I would like to be ;-)

Regards,

Petr
-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

[Doxygen-develop] RE: Doxygen and XML discussion... (was: Adding of new (all) HTML entities?)

[Prikryl,Petr <PRI...@sk...>]

Hi Xavier,

(Notice: I have just received new mail from doxygen-develop 
by Dimitri.  The notices below do not reflect his view -- being
written earlier.)

Xavier wrote...
>
> "Prikryl,Petr" wrote:
> 
> > Xavier wrote...
> > > I would like to add new entities of HTML. I am currently interested
> > > in Greek letters but all what is defined in HTML 4.0 would be
> > > interesting.

[...]

> > There are three cases when doxygen is forced to work with character
> > entities:
> >
> > 1. The entity is written in the sources as the entity reference
> >    (i.e. ø), and it is expected to be converted into other
> >    sequence (like "\\o{}" for LaTeX or something else for RTF, ...),
> >    or into binary form.
> 
> That was the case I am interested in. Very convenient if you work
> on an American keyboard and want to have French (or other)
> special characters.

If the output were XML, you could always use the known references
to character entities.

> > 2. The entity is written in binary form in the sources and it should
> >    be converted into a named character entity (like '&' to &)
> 
> Again as far as I am concerned, I prefer used entities because it
> will be interpreted the same whatever the charset used. (Well I hope)

The "predefined" character entities that we are talking about
are unambiguous.  However, you cannot be sure if any browser will
render them.

> > For future, I wish XML would be the only form produced by doxygen
> > (please, read it until the end before flaming me).  Then, the more
> > general approach should be taken.
> 
> It's certainly a good idea .. if there is still possibility (integrated in
> Doxygen) to have the current multiple output: HTML, LaTeX and others.

Doxygen could call the XML tool internally for the generated XML
output.  Users want the result.  They do not care how the things are
implemented.

> > In the XML output case in future (and also in the HTML case now),
> > the easiest and the most general solution would be to recognize the
> > syntax of any explicitly written entity (i.e. ø) and leave it
> > untouched.
> 
> I think this would be a good idea. Does it exist a single set of such
> entities? I don't speak about numerical entities that are not especially
> convenient even if it should be also availble in the case this idea is
> implemented. I mean a readable set like é OK it will be
> in English but it's more readable than é :)

There is not a single but several sets of definitions of the
entities.  As the characters are assigned unique binary
identification, the entities are defined unambiguosly. 

They have ISO definitions.  The handy place to look for their names,
Unicode #, Glyph, and ISO Description is for example the on-line
version of "DocBook: The Definitive Guide" by Norman Walsh and
Leonard Muellner.  Look for "III. DocBook Character Entity
Reference".

> > The reason is that the entity may be either defined
> > explicitly (XML, SGML), or predefined by DTD (HTML) or somehow else.
> > Some entities may be predefined only in some language supports.
> >
> > Doxygen should be transparent and pass through the character
> > entities as if it was any other word (with & and ;).
> 
> This would be nice if you have only one output in XML or HTML
> but anyway, you would need something to make conversion for
> other outputs.

This conversion can be done using XML tools.

> > Moreover, if a special binary character is used in the source, the
> > conversion process should generally consider three different
> > character encodings in the same time:
> >
> >  - source encoding
> >  - internal encoding of doxygen -- see TranslatorXxxx classes
> >  - output encoding
> >
> > And also, one human language may use several possible encoding
> > (e.g. ISO, Windows, DOS, or some former national de facto standard)
> > This is really nightmare.  If doxygen should work with everything on
> > the input and everything on the output, it would take a long time to
> > solve the problems.
> >
> > Solution? XML!
> 
> So you mean to use special character entities as a standard
> for Doxygen.

Not at all.  Here, by "special (binary) character" I mean
(unformally) any character that is not ASCII. While I can
occasionally type some ø in my Czech text, I will always
prefer using normal way of entering special Czech character (using
Czech keyboard).  They are entered into the file as bytes greater
than (say) 127.  Or possibly, I may use Unicode editor later.
The text still should be readable -- even in the editor window.
Writing my name like "Petr Přikryl" should be really
rare.

What I possibly could say that it should not matter whether you
decided to type special character in binary form (some encoding) or
using named character entities.  During processing XML documents,
the named character entities are replaced by the binary encoded
characters (Unicode), so there is no difference whether you type in
named character entity reference (with the correct entity
definition) or the binary form (in the corect encoding context).

Unlike XML tools, doxygen does not work internally with Unicode.
This is the reason, in my opinion, why the general encoding 
conversion support would be very difficult to implement.

> What about part \latexonly in source documentation.
> It must continue to work to my opinion. If not some users
> could be disappointed.

Well, I was a big fan of LaTeX earlier.  These days I think that
DocBook XML is better for future.

Anyway, I think that it is not a big problem to store
LaTeX source reliably inside the intermediate XML document and
extract real, LaTeX source from that XML doc.

> > Case 2: binary in sources, converted for the output
> > ===================================================
> >
> > If the source contains the special binary characters, then the HTML
> > (XML, SGML) output should be able to accept also the unchanged
> > binary form of the characters. In that case, the HTML (...) document
> > should explicitly say what character set is used.
> >
> >    <meta content="text/html; charset=windows-1250">
> >
> > For that purpose, the TranslatorXxxx implements the method
> > idLanguageCharset() which is used to produce the above mentioned
> > meta tag in the HTML output.
> 
> The charset should be precised in the input document in this case.
> Otherwise there could be some mismatch.

Exactly.  Now, doxygen expects the single implicit encoding of
input sources, single (implicit) encoding of the internal strings,
and single implicit encoding of the output.

If only one input encoding were used in all sources, then the
encoding could be marked in the Doxyfile (configuration).  However,
there should be also a possibility to change the encoding on-the-fly
-- i.e. some new doxygen tags.  This way some internal tables could
be used to unify the input, internal and output encodings.

The better approach would be to produce the intermediate XML
document with blocks of text with explicitly marked encoding (less
work for doxygen, no problem for XML tools).

> > Another question is how to produce a multi-language document.
> > I am afraid that this cannot be solved without XML output as the
> > final or intermediate format.
> 
> In this case, there is one solution, I don't know if it's the only
> one: Unicode. With other charset on 8 bits it's not possible
> to have complete multiple language facility.

Yes, exactly.  Unless, you can pass the problem to the XML tools.

In other words, if sources were stored using Unicode (or the like)
encoding, no problem would emerge.  However, this is not realistic.
The majority of USERS (and also tools) is not adapted to Unicode,
yet.

On the other hand, XML document can be produced using normal 8bit
character editors with explicit tags around marking the used
encoding. The XML tools convert the 8bit chars blocks-of-text into
Unicode internally, during the processing.  Doxygen would not need
to care if it produced the XML output postprocessed by XML tools.

> > The conversion into other output formats (like RTF, LaTeX, PDF,
> > etc.) should be done by XML tools. Otherwise, the doxygen would have
> > to implement all the character encoding conversions, character
> > entity reference conversions, and possibly other problems that are
> > already implemented by the XML tools.
> 
> OK but they must be integrated to Doxygen and transparent for
> the user who prefer HTML to XML even if this can be customized
> to have any output.

This would be ideal.  But the integration does not neccessarily
means to put everything into one binary executable.

> > In my personal opinion, future doxygen should focus on producing
> > quality XML output ONLY -- possibly using more than one markup
> > (DocBook XML be the major one, possibly also some proprietary XML in
> > the sense similar to producing RTF specific for some versions of
> > Microsoft Word).  Focusing on a single output form can make doxygen
> > lighter, faster, containing fewer bugs.
> 
> Yes but one interesting feature of Doxygen is precisely this
> multiple input/output. If using a intermediate XML output could
> be interesting, Doxygen should be able to provide the other
> output, even if it is done using other existing tools. And to use
> the multiple input. Currently only LaTeX and HTML I believe.

Yes, they are the strong and weak points at the same time.  

The strong point is that having one binary executable, you have
everything you need.

The problem is that it generally works correctly only for English
and possibly for few other languages.  To make it working for e.g.
Czech would require some non-trivial internal changes of doxygen.

Because of that, I guess that there will always be a group of users
who are satisfied with doxygen as-is, and who would be against the
big changes (the English language users).  They may claim that there
is nothing big to improve.

Another weak point is that the set of generated outputs is
restricted by doxygen.  As far as I know, the DocBook XML output 
could be used to produce all the outputs that one gets from doxygen
today.  Similarly, the input formats are restricted by the internal
parser (basically C/C++/Java) and only slightly extended via input
filters.

Someone named XML "the ASCII of the future", and there is a strong
evidence that DocBook DTD will dominate in the area of writing
technical documentation.  As far as I can imagine, there are no
limitations with respect what doxygen can produce now and also in
future.  

DocBook is said to be the second most widespread DTD (HTML is the
first one).  However, the HTML is rather more presentation-oriented.
In other words, HTML is used rather as the final form of documents.
DocBook, on the other hand, is better for capturing the structure of
the document with all the necessary redundancy for postprocessing
into more output forms.

LaTeX is somewhere between.  While its main plus is the ability to 
capture the structure of the document, it is still very special and
oriented to producing the final output, including some visual
details that are not reliably convertable into other form of the
output.

> Now choices have to be made and precise specifications written in
> a separate document. Mails are not enough to discuss seriously.

Exactly.  In my opinion, we should focuse on the back-end at the
beginning. 

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

Re: [Doxygen-develop] Adding of new (all) HTML entities?

[Dimitri v. H. <di...@st...>]

On Thu, Jul 19, 2001 at 12:37:10PM +0200, Xavier Outhier wrote:
> Hi,
> 
> 
> As far as I understand, what is to be done for each new entity
> is the following:
> 
> -1 Add a new pure virtual method named writeEntity() in
>     class BaseOutputDocInterface (outputgen.h)
> -2 Add a new method
>     void writeEntity()
>     { forall(&OutputGenerator::writeEntity); }
>    in class OutputList (outputlist.h)
> -3 Add non pure virtual method in generators:
>     void writeEntity()        {}
>    in classes
>     class ManGenerator (mangen.h)
>     class LatexGenerator (latexgen.h)
>     class HtmlGenerator (htmlgen.h)
> 
> Remarks:
> I do not understand what doc.cpp does really. I suppose it has also
> to be changed but I don't know how.

doc.cpp is a generated file. Look at the flex file doc.l: You'll see lines like
these:

<DocScan,Text>"&"[cC]"cedil;"           { outDoc->writeCCedil(yytext[1]); }

these consist of a set of states (between <>), a regular expression, 
and some code.

The code is executed when the input matches the regular expression. yytext
is a char* containing the actual text that was matched. So the
above matches &ccedil; and &Ccedil;

> Besides, I know what to do with HTML and LaTeX (maybe not for
> all symbols, I have to check in my documentation) but I don't know
> what to do with man.

This has always been a mistery to me too.


> Questions:
> Is the process (with the 3 steps) correct? Is something missing?

Seems ok to me.

> As my free time is so precious (as for everybody), is it possible
> tha I only change the files and send them back for merging,
> compiling and so on?

Yes, that is fine. You can choose to do only those entities that you
need as well.

Regards,
  Dimitri

Re: [Doxygen-develop] Status of XML development? (was Adding of n ew (all) HTML entities?)

[Dimitri v. H. <di...@st...>]

On Fri, Jul 20, 2001 at 09:42:21AM +0200, Prikryl,Petr wrote:
> Hi Michael and others,
> 
> Michael Lindig wrote...
> > you wish the XML feature. Have you an idea of the XML output format ?
> > think the format shall be like this:
> >
> > <DOXYGEN>
> >  	<file path="...">
> [snip]
> > Have you another idea ? 
> 
> There already is someone, who works on the XML part (Dimitri or someone
> else?). 

That will be me.

> If you look at doxygen/addon/xmlgen directory, you can find sources
> and also doxygen.dtd.  That person is definitely better in XML that I am.
> It is also important to have knowledge of doxygen's internal structures 
> (what elements are extracted by the parser) to choose the appropriate tags.

Well I'm not really an expert in XML, but I learn along the way.

> 
> This is not my case.  I am not prepared enough to discuss
> how the XML tags of doxygen should look like, or not.
> 
> However, I feel that XML is the right way to go, and I wish that more
> doxygen developers/users were interested in XML output.  Until now,
> I have only heard that some experimental XML support for doxygen
> is being implemented.  I understand, that possibly only one or two
> persons should work on that in the early stages of development.
> 
> In my last article I tried to explain why I wish the XML be the major
> intermediate and output format, and express my opinion on adding
> new character entities into doxygen generators.  Being one of the
> language maintainers, I was thinking hard about how the problems
> with special characters and various encoding should be solved.
> My personal opinion is that it would be endless work without XML.
> Briefly, XML is good for capturing semantics inside documents, and it
> solves the support for various languages and encodings.
> 
> Is anybody here (or any document) to explain current status of
> doxygen's XML development?

The XML development had been frozen for some time (due to lack of
time/priority mainly). Initially the XML support had been part of doxygen, 
but I later decided to move it outside of doxygen and prepare it to 
become an output plugin. Meanwhile my ideas have slightly changed.

The plans are to make XML output as part of doxygen again, with the
goal to replace the other output formats in the distant future
(but NOT before there is an equally powerful alternative for each).

I see XML output as an intermediate interface, that would allow
several front-ends to produce specific output (e.g. html output or
something very different like code metrics). The XML output would
contain all information, the front-ends will then pick the appropriate
information and transform that into the actual output.

In theory there are plenty of XML tools that can transform XML output
into something else. In practice these tools are just not there (at
least I haven't seen them). All that there really is, is an easy way to
parse XML and build up the structure contained in an XML file into
structures in memory. So the plan is to provide a C++/Qt based XML 
parser that understands doxygen's XML output. People that wish to
add support for another output format can do so by using the structures
build up by this parser.

The nice thing about having an intermediate
file is that the parser and front-end could also be written in another 
language such as Python. Furthermore, other input parsers could produce
the same XML output and benefit from the availble front-ends.

In summary doxygen would consist of the following:

- the main engine as a library
- the xml parser as a library
- an extendable configuration parser as a library (contains the
  config options for the engine, but can be dynamically extended by the
  front-ends to support more options).
- a number of front-ends, either as a libraries or as a standalone tools
- some glue to make a user friendly tool out of these.
  
With respect to DocBook format: I have looked at it, but I think it
covers only 20% of what doxygen will produce. So any docbook tool
(which are currently all SGML based by the way), wouldn't be very
useful.

I do not know how these ideas match/conflict with the character 
encoding problems mentioned by Petr. Would using XML like this still
solve all those problems?

Regards,
  Dimitri

Re: [Doxygen-develop] Adding of new (all) HTML entities?

[Xavier O. <xav...@an...>]

Ahoj Petre and the other,

"Prikryl,Petr" wrote:

> Hi Xavier and others,
>
> Xavier wrote...
> > I would like to add new entities of HTML. I am currently interested
> > in Greek letters but all what is defined in HTML 4.0 would be
> > interesting.
>
> The character entities in HTML are interpreted (i.e. rendered and
> displayed) by HTML browsers.  The HTML document should not care what
> the character entity means.  If the character in an HTML document
> has binary form, then the browser always uses additional information
> to know, how the character should be rendered -- the charset.

> In other words, it depends on HTML browser, whether the entity will
> be displayed as some special character, or not.
>
> So far, this is not related to doxygen at all.  However, HTML is not
> the only output format of doxygen.

It is a little, currently Doxygen allows to use some of these entities
in source input.

> There are three cases when doxygen is forced to work with character
> entities:
>
> 1. The entity is written in the sources as the entity reference
>    (i.e. ø), and it is expected to be converted into other
>    sequence (like "\\o{}" for LaTeX or something else for RTF, ...),
>    or into binary form.

That was the case I am interested in. Very convenient if you work
on an American keyboard and want to have French (or other)
special characters.

> 2. The entity is written in binary form in the sources and it should
>    be converted into a named character entity (like '&' to &)

Again as far as I am concerned, I prefer used entities because it
will be interpreted the same whatever the charset used. (Well I hope)

>
> 3. This case is not be related to named character entities; but
>    basically it requires conversion of a binary character into some
>    special, output-form related text sequence or binary form, like
>    in the first case.
>
> Case 1: entity reference in the sources, specific output
> ========================================================
>
> Firstly, the character entity references are not specific to the
> HTML doctypes.  The entities are known also in SGML and XML (no
> wonder).  In all of the mentioned markup languages, they are
> referred the same way: &identifier; Or they may have numeric form,
> related to Unicode characters (loosely speaking).
>
> XML and HTML output
> -------------------
>
> For future, I wish XML would be the only form produced by doxygen
> (please, read it until the end before flaming me).  Then, the more
> general approach should be taken.

It's certainly a good idea .. if there is still possibility (integrated in
Doxygen)
to have the current multiple output: HTML, LaTeX and others.

> In the XML output case in future (and also in the HTML case now),
> the easiest and the most general solution would be to recognize the
> syntax of any explicitly written entity (i.e. ø) and leave it
> untouched.

I think this would be a good idea. Does it exist a single set of such
entities? I don't speak about numerical entities that are not especially
convenient even if it should be also availble in the case this idea is
implemented. I mean a readable set like é OK it will be
in English but it's more readable than é :)

> The reason is that the entity may be either defined
> explicitly (XML, SGML), or predefined by DTD (HTML) or somehow else.
> Some entities may be predefined only in some language supports.
>
> Doxygen should be transparent and pass through the character
> entities as if it was any other word (with & and ;).

This would be nice if you have only one output in XML or HTML
but anyway, you would need something to make conversion for
other outputs.

> The only
> characters that must be converted for XML, SGML, and HTML outputs
> should be & and < (and probably > for the symetry).
>
> LaTeX, RTF, and other specific outputs
> --------------------------------------
>
> The problem is that character entity references -- and let's include
> also binary characters from the 3rd case -- must be converted to the
> very special form required by the output format.
>
> Moreover, if a special binary character is used in the source, the
> conversion process should generally consider three different
> character encodings in the same time:
>
>  - source encoding
>  - internal encoding of doxygen -- see TranslatorXxxx classes
>  - output encoding
>
> And also, one human language may use several possible encoding
> (e.g. ISO, Windows, DOS, or some former national de facto standard)
> This is really nightmare.  If doxygen should work with everything on
> the input and everything on the output, it would take a long time to
> solve the problems.
>
> Solution? XML!

So you mean to use special character entities as a standard
for Doxygen.
What about part \latexonly in source documentation.
It must continue to work to my opinion. If not some users
could be disappointed.


> Case 2: binary in sources, converted for the output
> ===================================================
>
> If the source contains the special binary characters, then the HTML
> (XML, SGML) output should be able to accept also the unchanged
> binary form of the characters. In that case, the HTML (...) document
> should explicitly say what character set is used.
>
>    <meta content="text/html; charset=windows-1250">
>
> For that purpose, the TranslatorXxxx implements the method
> idLanguageCharset() which is used to produce the above mentioned
> meta tag in the HTML output.

The charset should be precised inthe input document in this case.
Otherwise there could be some mismatch.

> Again, Doxygen should be transparent and pass through the character
> entities as if it was any other word (with & and ;). The only
> characters that must be converted for XML, SGML, and HTML outputs
> should be &amp; and &lt; (and probably &gt; for the symetry).
>
> Another question is how to produce a multi-language document.
> I am afraid that this cannot be solved without XML output as the
> final or intermediate format.

In this case, there is one solution, I don't know if it's the only
one: Unicode. With other charset on 8 bits it's not possible
to have complete multiple language facility.

> Conclusion: XML output is the answer!

> =====================================

> Trying to convert every special binary character to its character
> entity reference or vice versa -- with respect to the output format
> and input/output character encodings -- would require much work and
> is not acceptable with respect to the future, and with respect to
> the work already done in XML and the like fiels.
>
> The conversion into other output formats (like RTF, LaTeX, PDF,
> etc.) should be done by XML tools. Otherwise, the doxygen would have
> to implement all the character encoding conversions, character
> entity reference conversions, and possibly other problems that are
> already implemented by the XML tools.

OK but they must be integrated to Doxygen and transparent for
the user who prefer HTML to XML even if this can be customized
to have any output.

> In my personal opinion, future doxygen should focus on producing
> quality XML output ONLY -- possibly using more than one markup
> (DocBook XML be the major one, possibly also some proprietary XML in
> the sense similar to producing RTF specific for some versions of
> Microsoft Word).  Focusing on a single output form can make doxygen
> lighter, faster, containing fewer bugs.

Yes but one interesting feature of Doxygen is precisely this
multiple input/output. If using a intermediate XML output could
be interesting, Doxygen should be able to provide the other
output, even if it is done using other existing tools. And to use
the multiple input.Currently only LaTeX and HTML I believe.

> [...]
> See you,
>   Petr
>
> P.S. I may be wrong.  But I am always ready to listen to your arguments.
>
>      Do not multiply [character] entities.

I agree from the long term perspective. I simply proposed that because
that's the way it is currently. I already ask for adding &Ccedil;, yes it's
because of me it is in doxygen. :) I tought that I could help to do the rest

(what exist for HTML 4.0). I would not be able to do what you describe.

But indeed your idea, from the _user_ point of view, will be similar to
mine.
It's a kind of generalisation of what exist already.
Except for non \latexonly or \htmlonly sections where usage of non-LaTeX or
non-HTML is not relevant, the only one way to write special character
for Doxygen documentation would be using entities.

Now choices have to be made and precise specifications written in
a separate document. Mails are not enough to discuss seriously.
I may have time to review it but not writing it neither to develop it. :(

Greetings,

Xavier.
--
 Artificial Anthill Project
  http://www.aanthill.org/
  mailto:aan...@aa...

 D2SET Non Profit Association
  http://www.d2set.org/
  mailto:d2...@d2...

RE: [Doxygen-develop] Status of XML development? (was Adding of n ew (all) HTML entities?)

[Prikryl,Petr <PRI...@sk...>]

Hi Michael and others,

Michael Lindig wrote...
> you wish the XML feature. Have you an idea of the XML output format ?
> think the format shall be like this:
>
> <DOXYGEN>
>  	<file path="...">
[snip]
> Have you another idea ? 

There already is someone, who works on the XML part (Dimitri or someone
else?).  If you look at doxygen/addon/xmlgen directory, you can find sources
and also doxygen.dtd.  That person is definitely better in XML that I am.
It is also important to have knowledge of doxygen's internal structures 
(what elements are extracted by the parser) to choose the appropriate tags.

This is not my case.  I am not prepared enough to discuss
how the XML tags of doxygen should look like, or not.

However, I feel that XML is the right way to go, and I wish that more
doxygen developers/users were interested in XML output.  Until now,
I have only heard that some experimental XML support for doxygen
is being implemented.  I understand, that possibly only one or two
persons should work on that in the early stages of development.

In my last article I tried to explain why I wish the XML be the major
intermediate and output format, and express my opinion on adding
new character entities into doxygen generators.  Being one of the
language maintainers, I was thinking hard about how the problems
with special characters and various encoding should be solved.
My personal opinion is that it would be endless work without XML.
Briefly, XML is good for capturing semantics inside documents, and it
solves the support for various languages and encodings.

Is anybody here (or any document) to explain current status of
doxygen's XML development?

Thanks,
  Petr

-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

RE: [Doxygen-develop] Adding of new (all) HTML entities?

[Michael L. <li...@ea...>]

Hi Petr,

you wish the XML feature. Have you an idea of the XML output format ?

I think the format shall be like this:

<DOXYGEN>
 	<file path="...">
		<comment>
    			<line>x</line>
    	<column>y</column>
			<brief>...</brief>
			<detail>...</detail>
			...
		</comment>
  		<includes>
   			<include identifier="include_path">
    			<line>x</line>
    				<column>y</column>
</include>
   			...
  		</includes>
  		<macros>
   			<macro identifier="...">
		<comment>
					<line>x</line>
    			<column>y</column>
			<brief>...</brief>
			<detail>...</detail>
			...
		</comment>
    				<line>x</line>
    				<column>y</column>
    				<argument identifier="...">
		<comment>
    						<line>x</line>
    				<column>y</column>
			<brief>...</brief>
			<detail>...</detail>
			...
		</comment>
     					<line>x</line>
     					<column>y</column>
    				</argument>
     				...more arguments
    			<tokenstring>
     					<!CDATA[... the macro definition ...]]>
    				</tokenstring>
   			</macro>
   			...
  		</macros>
  		<classes>...</classes>
		<functions>...</functions>
 	</file>
	...
</DOXYGEN>

Have you another idea ? 

Bye,
Michael Lindig

RE: [Doxygen-develop] Adding of new (all) HTML entities?

[Prikryl,Petr <PRI...@sk...>]

Hi Xavier and others,

Xavier wrote...
> I would like to add new entities of HTML. I am currently interested
> in Greek letters but all what is defined in HTML 4.0 would be
> interesting.

The character entities in HTML are interpreted (i.e. rendered and
displayed) by HTML browsers.  The HTML document should not care what
the character entity means.  If the character in an HTML document
has binary form, then the browser always uses additional information
to know, how the character should be rendered -- the charset.

In other words, it depends on HTML browser, whether the entity will
be displayed as some special character, or not.

So far, this is not related to doxygen at all.  However, HTML is not 
the only output format of doxygen.

There are three cases when doxygen is forced to work with character
entities:

1. The entity is written in the sources as the entity reference
   (i.e. ø), and it is expected to be converted into other
   sequence (like "\\o{}" for LaTeX or something else for RTF, ...),
   or into binary form.

2. The entity is written in binary form in the sources and it should
   be converted into a named character entity (like '&' to &)

3. This case is not be related to named character entities; but
   basically it requires conversion of a binary character into some
   special, output-form related text sequence or binary form, like
   in the first case.


Case 1: entity reference in the sources, specific output 
========================================================

Firstly, the character entity references are not specific to the
HTML doctypes.  The entities are known also in SGML and XML (no
wonder).  In all of the mentioned markup languages, they are
referred the same way: &identifier; Or they may have numeric form,
related to Unicode characters (loosely speaking).

XML and HTML output
-------------------

For future, I wish XML would be the only form produced by doxygen
(please, read it until the end before flaming me).  Then, the more
general approach should be taken.

In the XML output case in future (and also in the HTML case now),
the easiest and the most general solution would be to recognize the
syntax of any explicitly written entity (i.e. ø) and leave it
untouched. The reason is that the entity may be either defined
explicitly (XML, SGML), or predefined by DTD (HTML) or somehow else.
Some entities may be predefined only in some language supports.

Doxygen should be transparent and pass through the character
entities as if it was any other word (with & and ;). The only
characters that must be converted for XML, SGML, and HTML outputs
should be & and < (and probably > for the symetry).


LaTeX, RTF, and other specific outputs
--------------------------------------

The problem is that character entity references -- and let's include
also binary characters from the 3rd case -- must be converted to the
very special form required by the output format.  

Moreover, if a special binary character is used in the source, the
conversion process should generally consider three different
character encodings in the same time:

 - source encoding
 - internal encoding of doxygen -- see TranslatorXxxx classes
 - output encoding
 
And also, one human language may use several possible encoding
(e.g. ISO, Windows, DOS, or some former national de facto standard)
This is really nightmare.  If doxygen should work with everything on
the input and everything on the output, it would take a long time to
solve the problems.

Solution? XML!


Case 2: binary in sources, converted for the output
===================================================

If the source contains the special binary characters, then the HTML
(XML, SGML) output should be able to accept also the unchanged
binary form of the characters. In that case, the HTML (...) document
should explicitly say what character set is used. 

   <meta content="text/html; charset=windows-1250">

For that purpose, the TranslatorXxxx implements the method
idLanguageCharset() which is used to produce the above mentioned
meta tag in the HTML output.

Again, Doxygen should be transparent and pass through the character
entities as if it was any other word (with & and ;). The only
characters that must be converted for XML, SGML, and HTML outputs
should be &amp; and &lt; (and probably &gt; for the symetry).

Another question is how to produce a multi-language document.
I am afraid that this cannot be solved without XML output as the 
final or intermediate format.  


Conclusion: XML output is the answer!
=====================================

Trying to convert every special binary character to its character
entity reference or vice versa -- with respect to the output format
and input/output character encodings -- would require much work and
is not acceptable with respect to the future, and with respect to
the work already done in XML and the like fiels.

The conversion into other output formats (like RTF, LaTeX, PDF,
etc.) should be done by XML tools. Otherwise, the doxygen would have
to implement all the character encoding conversions, character
entity reference conversions, and possibly other problems that are
already implemented by the XML tools.

In my personal opinion, future doxygen should focus on producing
quality XML output ONLY -- possibly using more than one markup
(DocBook XML be the major one, possibly also some proprietary XML in
the sense similar to producing RTF specific for some versions of
Microsoft Word).  Focusing on a single output form can make doxygen
lighter, faster, containing fewer bugs.

In XML, one can say that the block of text uses certain character
encoding -- no problem with multiple character encodings in one
document and even one file -- which would be great for doxygen:
 
 * The block of text from input can be passed without problems
   in binary form to the output.
 * The sentences generated by doxygen can use some internal
   encoding without any conversion.
 * If the character is written as known entity reference, then it 
   is always unique and can be passed without problems.

In the best case, doxygen could call (in addition) external XML tools
to produce other output forms (technically the same way
as 'dot' is called these days -- "user need not know that"). 

For backward compatibility, the other directly produced output
format (i.e. the outputs produced these days) should stay supported
for a while, but their development should be frozen at the same time
when the same or very similar could be produced using XML output and
XML tools.


See you,
  Petr

P.S. I may be wrong.  But I am always ready to listen to your arguments.

     Do not multiply [character] entities.
                                            Occam ;-)
-- 
Petr Prikryl, SKIL, spol. s r.o., pri...@sk...

[Doxygen-develop] Adding of new (all) HTML entities?

[Xavier O. <xav...@an...>]

Hi,

Proposition:
I would like to add new entities of HTML. I am currently interested in
Greek letters but all what is defined in HTML 4.0 would be interesting.
There are 3 files containing all these entities:
 HTMLlat1.ent.htm (Doxygen already have some of them)
 HTMLspecial.ent.htm  (Doxygen already have some of them)
 HTMLsymbol.ent.htm
There are available at:
http://www.w3.org/TR/1998/REC-html40-19980424/struct/global.html#idx-entity_sets.

Does someone is working on that?

I don't know exactly what is to be changed.

I have made a search for sharpS. One entity already implemented
and I have found:
Searching for 'SharpS'...
C:\doxygen-1.2.8.1\src\doc.cpp(17976):{ outDoc->writeSharpS();
}
C:\doxygen-1.2.8.1\src\htmlgen.h(177):    void writeSharpS()        { t
<< "&szlig;"; }
C:\doxygen-1.2.8.1\src\latexgen.h(182):    void writeSharpS()       { t
<< "\"s"; }
C:\doxygen-1.2.8.1\src\mangen.h(166):    void writeSharpS()        { t
<< "s\\*:";     /* just a wild guess,
C:\doxygen-1.2.8.1\src\outputgen.h(207):    virtual void writeSharpS() =
0;
C:\doxygen-1.2.8.1\src\outputlist.h(301):    void writeSharpS()
C:\doxygen-1.2.8.1\src\outputlist.h(302):    {
forall(&OutputGenerator::writeSharpS); }
C:\doxygen-1.2.8.1\src\rtfgen.h(164):    void writeSharpS()       { t <<
"\337"; }
8 occurrence(s) have been found.

As far as I understand, what is to be done for each new entity
is the following:

-1 Add a new pure virtual method named writeEntity() in
    class BaseOutputDocInterface (outputgen.h)
-2 Add a new method
    void writeEntity()
    { forall(&OutputGenerator::writeEntity); }
   in class OutputList (outputlist.h)
-3 Add non pure virtual method in generators:
    void writeEntity()        {}
   in classes
    class ManGenerator (mangen.h)
    class LatexGenerator (latexgen.h)
    class HtmlGenerator (htmlgen.h)

Remarks:
I do not understand what doc.cpp does really. I suppose it has also
to be changed but I don't know how.
Besides, I know what to do with HTML and LaTeX (maybe not for
all symbols, I have to check in my documentation) but I don't know
what to do with man.

Questions:
Is the process (with the 3 steps) correct? Is something missing?
As my free time is so precious (as for everybody), is it possible
tha I only change the files and send them back for merging,
compiling and so on?

Greetings,

Xavier.
--
 Artificial Anthill Project
  http://www.aanthill.org/
  mailto:aan...@aa...

 D2SET Non Profit Association
  http://www.d2set.org/
  mailto:d2...@d2...

[Doxygen-develop] New tags...

[John O. <jo...@ly...>]

I propose that three new tags are added

@run
@endrun
@filename

Why do I need these tags and what do they do?

The problem I'm trying to solve is that I want to add the ClearCase (our
version control system at work) version number for the documented files in
the generated documentation. And while doing this I thought that I could
solve a more general problem at the same time. :)

The @run and @endrun tags are a pair, much like the @link and @endlink
tags. The tags are used for calling a program and inserting everything
that the program sends to its stdout directly into the generated file.
Thus I could, for instance, write a simple script that extracted the
intersting information using the cleartool command and so on. :)

I have done a prototype implementation of this based on the iSystem()
function found in util.cpp, but since I'm not a Windows programmer I have
only done the Unix part of it...

The @filename tag simply inserts the full filename (path + filename) of
the current file in the generated documentation and in my current
prototype implementation it can only be used between the @run and @endrun
tags. It simplifies life if you do not need to hardcode this in the source
code...

So, if I tidied up my implementation, would this be something that you
think would be useful for others? If so, could someone help me with the
windows programming bit?


Perhaps I should give you an example? Here it is

/**
 * @file foo.c
 * ClearCase version: @run myScript @filename @endrun
 */

When the parser recognises the @run (and @filename) tag(s), the following
command is executed

myScript /vobs/myvob/foo.c

And the output from this script could look like this

/vobs/myvob/foo.c@@/main/mybranch/17

And finally this is inserted into the generated documentation, resulting
in this

ClearCase version: /vobs/myvob/foo.c@@/main/mybranch/17


/John

[Doxygen-develop] Doxygen developers mailing list

[Dimitri v. H. <di...@st...>]

Hi,

This mail is to announce the existance of a mailing list for doxygen 
developers (this list has actually been there for a while, but so far I never
really used or mentioned it).

The list is meant for development related discussion, patches, language
updates, and such. For this purpose messages can be up to 500K in size
(on the users list there is a limit of 40K).

Subscription information can be found at: 
http://lists.sourceforge.net/lists/listinfo/doxygen-develop

Regards,
  Dimitri