Doxygen: Formatierung der mainpage

[Bot-Builder]

Guten Abend allerseits!

Ich beschäftige mich nun schon einige Tage mit den Formatierungsmöglichkeiten der mainpage wie sie von Doxygen 1.7.2 erzeugt wird. Als Beispiel dient mir folgender Codeteil, der mit Programmers Notepad 2 erstellt wird (und dann weiter mit WinAVR-20100110; daher der Post hier an dieser Stelle).

/**
    @file        DoxygenTest_V2.c
    @brief      Programm um die Funktion von Doxgen zu testen
    @author   <b>Bot-Builder</b>
/**
    @mainpage    Startseite DoxygenTest
<p><b>Doxygen Version:</b>    1.7.2
<p>erste Zeile
<p>zweite Zeile
<p>dritte Zeile
<p>also 'p' erzeugt einen Zeilenvorschub, aber mit Abstand. Wie erzeugt man einen Zeilenvorschub ohne Abstand? Das sollte einmal geklärt werden. Und auch wie ein lange Zeile aussieht. Bei langen Zeilen gibt es keinen Abstand zwischen den Zeilen. Warum dann bei 'p'?
<p><b>Ports:</b>
<p>
<p>        PA1:        LED rot
<p>
<p>        PA2:        LED grün
<p>
<p>        PA3:        LED gelb
<p>                    alternativ Schalter A
<p>so funktionieren die Einzüge nicht. TABs werden einfach ignoriert.
<p>-
<p>und wie erzeugt man Leerzeilen, wenn man Abstände will?
<p>-
<p>und jetzt das Ganze als Liste
<p><b>Ports:</b>
<p>\li PA1    LED rot
<p>\li PA2    LED grün
<p>\li PA3    LED gelb<p>alternativ Schalter A
<p>und jetzt das Ganze als HTML
 @htmlonly
<table border=&quot;0&quot; cellpadding=&quot;0&quot; cellspacing=&quot;2&quot;>
<colgroup>
    <col width=&quot;100&quot;>
    <col width=&quot;100&quot;>
  </colgroup>
 <tr>
  <td valign=&quot;top&quot;><b>Ports:</b></td>
  <td valign=&quot;top&quot;>PA1</td>
  <td valign=&quot;top&quot;>LED rot</td>
 </tr>
 <tr>
  <td></td>
  <td valign=&quot;top&quot;>PA2</td>
  <td valign=&quot;top&quot;>LED grün</td>
 </tr>
 <tr>
  <td></td>
  <td valign=&quot;top&quot;>PA3</td>
  <td valign=&quot;top&quot;>LED gelb<p>alternativ Schalter A</td>
 </tr>
</table>
Das scheint so im Grossen und Ganzen zu funktionieren. Ist aber im Quelltext nur sehr schlecht zu lesen. Und es bleibt immer noch die Frage, wie man eine neue Zeile und nicht gleich einen neuen Absatz erzeugt.
 @endhtmlonly
*/

Wenn der Code nun mit Doxygen ausgewertet wird, erhalte ich folgende html-Seite (hier als Druckversion; habe es leider nicht hinbekommen, die html-Version als fertige Ansicht ein zu stellen):



Mir geht es vor allem um die Darstellung mit Tabulatoren und Einzügen. Eigentlich würde ich mir ein Ergebniss wie das grün umrandete wünschen, aber das ist im Quelltext nur sehr schwer zu lesen. Und die Umsetzung als Tabelle ist sehr umständlich und aufwendig. Die im Quelltest einfach zu lesende Variante wird aber von Doxygen nicht richtig umgesetzt. Oder mache ich hier irgend etwas falsch? Habe ich vielleicht was in den Einstellungen von Doxygen übersehen?

Und dann auch noch die Frage, wie man eine neue Zeile, nicht aber gleich einen neuen Absatz erzwingt.

Hat dazu jemand vielleicht eine Idee?

Würde mich freuen.

Und bei der Gelegenheit: Wie kann man eine html-Seite als sichtbare Version (also nicht als Code) einstellen?


Viele Grüsse

Bot-Builder

.

[markusj]

Steht mit Sicherheit irgendwo in der Doku, du kannst nicht mit Tabs (oder sogar Whitespace allgemein, bin mir nicht ganz sicher) formatieren. Nimm eine Tabelle, die sind genau für diesen Zweck gedacht, oder drücke das was du schreiben möchtest, auf anderem Wege aus.
Doxygen ist eben kein WYSIWYG-Werkzeug ...

mfG
Markus

[.:Sebastian:.]

Moin

Also zunächst mal ist dein hmtl gelinde gesagt etwas ... äh strange.
Zu jedem öffnenden <p> gehört normaler weise auch ein schließendes </p>.
P steht für paragraph und wird in html dazu genutzt eine Absatz Text zu definieren.

<p>Dieser Text ist mein erster Absatz. Blabla Lalala</p>
<p>Die ist mein zweiter Absatz.</p>

Du willst aber Zeilenumbrüche, wenn ich dich richtig verstehe.
Die macht man in html mit <br/>. Sieht aber in dem Kommentaren potthässlich aus.
Deshalb hat Doxygen dafür das \n eingeführt.

Wenn du wirklich eine Tabelle willst und nicht mit der Listen Darstellung leben kannst,
wirst du halt mit @htmlonly arbeiten müssen.
Tabs kann hmtl nämlich nicht. (text-indent mit css ist das höchste der Gefühle)

Allerdings würde ich mich da einschränken, damit das ganze halbwegs manierlich aussieht.

<table border="0" cellpadding="0"; cellspacing="2">
 <tr>
  <td><b>Ports:</b></td>
  <td>PA1</td>
  <td>LED rot</td>
 </tr>
 <tr>
  <td></td>
  <td>PA2</td>
  <td>LED grün</td>
 </tr>
 <tr>
  <td></td>
  <td>PA3</td>
  <td>LED gelb<p>alternativ Schalter A</td>
 </tr>
</table>

Ich bin mir da nicht mehr ganz sicher aber ich glaube du musst die " nicht escapen.
Was noch dazu kommt : http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
Da steht Note that although these HTML tags are translated to the proper commands for output formats other than HTML, all attributes of a HTML tag are passed on to the HTML output only.
Sprich wenn du mal ein PDF oder ähnliches erzeugst sieht deine Tabelle sowieso ganz anders aus.
Von daher wäre in meinen Augen die Lösung als liste zu bevorzugen.

Wenn es aber unbedingt Tabellen sein müssen, würde ich das nicht in den Sourcecode packen.
(Ist bei der Mainpage sowieso die Frage in wie weit die in den Sourcecode rein sollte.)
Mach die Tabelle als externe html Datei und benutze /htmlinclude (http://www.stack.nl/~dimitri/doxygen...cmdhtmlinclude)
Und wenn du die Info trotzdem zusätzlich noch im Source haben willst, schreibs rein benutze Tabs und lass es Doxygen ignorieren.
Siehe Doxygen FAQ Punkt 4.
Dann musst da aber zwei Dateien pflegen.

Du siehst einen Tod wirst du so oder so sterben, Doxygen ist halt nicht OpenOffice und was noch dazu kommt nicht nur speziell zum erstellen von HTML-Seiten gedacht.

Gruß und gute Nacht (ich hau mich jetzt auch mal hin)
Sebastian

[Bot-Builder]

Moin!

... drücke das was du schreiben möchtest, auf anderem Wege aus.

Okay, aber was gibt es denn noch für andere Wege?

Also zunächst mal ist dein hmtl gelinde gesagt etwas ... äh strange.
Zu jedem öffnenden <p> gehört normaler weise auch ein schließendes </p>.

...
Die macht man in html mit <br/>. Sieht aber in dem Kommentaren potthässlich aus.
Deshalb hat Doxygen dafür das \n eingeführt.

Das sind meine ersten Gehversuche mit html. Und das kann man leider sehen. Habe Deine Hinweise mit <p>, </p> schon umgesetzt. Das mit <br\> bzw. \n habe ich ganz zu Anfang meiner Versuche mal probiert, hat da aber nicht funktioniert und dann habe ich es nicht weiter verfolgt. Das ist aber wohl was schief gelaufen, jetzt gehts.

Von daher wäre in meinen Augen die Lösung als liste zu bevorzugen.

Wenn es aber unbedingt Tabellen sein müssen, würde ich das nicht in den Sourcecode packen.
(Ist bei der Mainpage sowieso die Frage in wie weit die in den Sourcecode rein sollte.)
Mach die Tabelle als externe html Datei und benutze /htmlinclude

Ich werde es dann wohl so machen, wie Du vorgeschlagen hast. Bei schnellen Lösungen mit Listen. Und wenn es optisch schön sein soll, mit ausgelagerter reinen html mainpage.

Danke für Deine Tips.

Und Grüsse in den Kristallpalast auf Arkon I.

Bot-Builder