Eine kurze Anleitung, wie man Dokumentationen
mit Doxygen erstellt und auf dem Server ablegt.


1. Im Allgemeinen werden nur die *.hh-Dateien dokumentiert.
   Dort muss also alles drin stehen, was einen Anwender so
   interessieren könnte. Als Beispiele kann man sich die
   Projekte 'alarm' oder 'accdevice' angucken. Das Doxygen-
   Handbuch findet man unter
   www.stack.nl/~dimitri/doxygen/manual.html.


2. Directory 'doc' ersellen

    $ cd ~/workspace/<project>
    $ mkdir doc


3. Entweder Default 'Doxyfile' auf 'doc' generieren

    $ cd doc
    $ doxygen -g

  und die Datei editieren. Siehe dazu Punkt 4.
  Oder die Vorlage aus dem Projekt 'uti' benutzen 

    $ cd doc
    $ cp $uti/Doxyfile.template Doxyfile

  und die darin mit '[tbs]' gekennzeichneten Stellen 
  anpassen bzw. ergänzen. Danach weiter mit Punkt 5.
  Zur Erklärung evtl. in Punkt 4 nachlesen.


4. Doxyfile-Vorlage editieren.

   a. Einige Tags müssen angepasst werden. Hier ein Beispiel
      für das Projekt MX:

      PROJECT_NAME           = "MX - Equipment Model for Pulsed Magnets"
      ALWAYS_DETAILED_SEC    = YES
      EXTRACT_STATIC         = YES
      INPUT                  = ../
                               /usr/local/acc/production/include/asl/current \
                               /usr/local/acc/production/include/vme/current \
      FILE_PATTERNS          = default-usrs.hh \
                               default-usrs-vme.hh \
                               therapy-usrs.hh \
                               therapy-*-usrs.hh \
                               mx-*-adapter.hh \
                               x2y.hh \
                               mx-helpers.hh \
                               mx-device.hh \
                               mx-usrs.hh
      ALIASES                = "updates=\par Updates:\n" \
                               "eqmodversion=\par Equipment model version:\n" \
                               "property=\par Property:"  \
                               "call=\par Call:\n"
      WARN_IF_UNDOCUMENTED   = YES
      GENERATE_TREEVIEW      = YES
      INCLUDE_PATH           = /usr/local/acc/production/include/asl/current \
                               /usr/local/acc/production/include/vme/current

      Unter 'FILE_PATTERNS' werden die Dateien aufgeführt, die
      Incode-Doku enthalten, deren Dirctory, in der Regel '../',
      unter 'INPUT'. Dokumentierte Dateien, die von den angegebenen 
      Dateien inkludiert werden, z.B. mx-dev-def.hh, müssen nicht 
      angegeben werden, aber deren Directories. 

      Für USRs gilt: 
      - Default- und Therapie-USRs müssen (leider) explizit
        angegeben werden. 
      - Entweder 'default-usrs-vme.hh' oder 'default-usrs-x86.hh' 
        angeben. 
      - Nur die Therapie-USRs angeben, die vom Gerätemodell
        benutzt werden.
      - Möchte man die USR-Adapter dokumentiert haben, diese
        unter FILE_PATTERNS passend definieren. 

   b. Möchte man Beispiel-Programme einbinden, sollten diese
      auf 'doc' liegen. Dann braucht man

      EXAMPLE_PATH           = .
      EXAMPLE_PATTERNS       = *.hh *.cc

   c. LaTeX braucht man in der Regel nicht.

      GENERATE_LATEX         = NO

   d. Nervt der Bildschirm-Output von doxygen, dann

      QUIET                  = YES


5. Dokument generieren

    $ doxygen

   Es wird eine Directory ~/workspace/<project>/doc/html
   erstellt und die erstellten Dateien dort abgelegt.
   Die Datei 'index.html' ist die Start-Datei für den Browser.

   Entsprechende Directories werden erzeugt, wenn LaTeX-
   Output usw. aktiviert ist.


6. Inhalt des Directories 'html' auf den Server kopieren. 

   * Am einfachsten geht es wohl mit cadaver.

     a. Wechseln nach ~/workspace/<project>/doc/html

     b. Cadaver aufrufen und einloggen.

          $ cadaver https://www.acc.gsi.de/dav/documentation/<project>
          Userame:
          Password:

        Bei Gerätemodellen ist das '<project>' in der URL 
        gleich 'eq-models/<eqmod>'.

     c. Alle Dateien kopieren

          dav:/dav/documentation/<project>/> mput *

     Existiert das Ziel-Directory noch nicht, kann man 
     es mit cadaver auch erzeugen.

       dav:/dav/documentation/> mkcol <project>


   * Man kann auch den Konqueror benutzen, Aufruf 
     einfach mit

       $ konqueror &

     im Terminalfenster und vorgehen wie folgt.

     a. Wechseln nach ~/workspace/<project>/doc/html

     b. Alle Dateien selektieren (select all) und kopieren 
        (copy) (mit Hilfe der Ringfinger-Maustaste - was für 
        Rechtshänder die rechte ist).

     c. Wechseln nach 'webdavs://www-acc.gsi.de/dav/documentation/'.
        Einloggen mit Linux-Username und Passwort.
        Dann sollte man die verschiedenen <project>-Directories
        sehen, z.B. 'accdata', 'alarm', 'eq-models' usw.

     d. In das <project>-Directory wechseln und Dateien einfügen 
        (paste), wobei man die alten Dateien überschreibt 
        (overwrite all).

     Es wird nicht empfohlen, das komplette Directory 'html'
     zu kopieren und es im Zielverzeichnis in <project> 
     umzubenennen, wobei das alte <project>-Directory gelöscht
     werden muss. Im alten Directory können noch weitere Dateien
     liegen, die dann mitgelöscht würden, was zu toten Links 
     im Wiki führt.
   

   * Das Kopieren geht auch mit Eclipse, das scheint aber etwas
     unhandlich zu sein. Wer rausgefunden hat, wie es richtig
     geht, sage bitte Bescheid.


7. Ebenso wird die PDF-Datei des Gerätemodells auf den Server 
   kopiert. Beispiel mit cadaver:

   a. Wechseln nach ~/workspace/<eqmod>/doc

   b. $ cadaver https://www.acc.gsi.de/dav/documentation/eq-models/<eqmod>
      Userame:
      Password:

      dav:/dav/documentation/eq-models/<eqmod>/> put gm-<eqmod>.pdf

   Beachten: Das 'eq-models' in der URL und 'put' statt 'mput'.


8. Nun kann man sich mit jedem Browser von jedem Rechner aus
   die Doku unter "http://www-acc.gsi.de/data/documentation/"
   angucken.

   Im BEL-Wiki gibt es unter "Documentation" die Links 
   "Device Access" und "Equipment Models", die dort hin 
   verweisen.