Rozdział 13. Automatycznie generowana dokumentacja do programów technologicznych przy użyciu skryptu docgen

Spis treści
13.1. Sposób użycia skryptu docgen
13.2. Dokumentacja programów technologicznych
13.2.1. Wykorzystanie preprocesora języka C
13.2.2. Sekcja parametrów programowalnych stałych
13.2.3. Sekcja parametrów programowalnych - paczek czasowych
13.2.4. Sekcja parametrów wyświetlanych
13.2.5. Sekcja wejść analogowych
13.2.6. Sekcja pomiarów analogowych
13.2.7. Sekcja wejść binarnych
13.2.8. Sekcja wyjść analogowych
13.2.9. Sekcja wyjść przekaźnikowych
13.2.10. Sekcja komentarza ogólnego
13.2.11. Sekcja komentarzy dołączalnych
13.2.12. Dołączanie komentarzy z zewnętrznych plików
13.2.13. Wstawianie formuł matematycznych
13.2.14. Parametryzowanie komentarza zmiennymi
13.2.15. Automatycznie generowane opisy parametrów na podstawie konfiguracji
13.3. Automatyczne sprawdzanie poprawności ortograficznej
13.4. Dobre zwyczaje obowiązujące przy pisaniu dokumentacji
13.5. Generowanie dokumentacji do pliku PDF

Skrypt docgen został napisany w języku Perl i służy do automatycznego generowania dokumentacji i innych zasobów na podstawie plików źródłowych programów technologicznych. Kod źródłowy programu technologicznego jest napisany w języku C i składa się z dwóch plików: prefwyk.c oraz prefdefi.h. Przedrostek o nazwie pref w nazwach plików źródłowych jest oznaczeniem programu technologicznego i może w zależności od przeznaczenia programu technologicznego przyjmować różne nazwy. Aby dokumentacja tworzona na podstawie plików źródłowych była prawidłowo wygenerowana pliki muszą posiadać odpowiednio zaznaczone komentarze. W części dotyczącej dokumentacji programów technologicznych zostanie wyjaśniony szczegółowo sposób tworzenia komentarzy.

13.1. Sposób użycia skryptu docgen

Poniższe wywołanie skryptu wyświetli pomoc:

$ ./docgen.pl

Skrypt do generowania dokumentacji z plików źródłowych programów technologicznych

Uzycie:
   ./docgen.pl prefix [-h] [-t] [-m] [-x] [-n <numer urzadzenia>]

Parametry wywolania:
   prefix - nazwa (czteroliterowy poczatek) kompilowanego programu
        (parametr obowiazkowy), np /opt/szarp/bin/docgen.pl weze;
        mozna ja rowniez podac w formie "z wbudowanym numerem urzadzenia"
        np. /opt/szarp/bin/docgen.pl kocz_2

   -h - generuj dokumentacje w formacie pliku HTML

   -p - generuj dokumentację w formacie pliku PDF (przy użyciu OO.org), załącza opcje -h -s

   -o - dodaj przesunięcie do numerów stron w pliku PDF, załącza opcję -p

   -s - automatycznie dostosowuj wielkość grafiki na potrzeby pliku PDF

   -t - generuj plik z tabelą do wydruku

   -x - generuj plik XML z konfiguracją parametrów stałych i paczek czasowych
        (dla draw3)

   -m - wyslij liste bledow poczta zamiast wyswietlac ja na ekranie

   -n <numer urzadzenia> - wygeneruj dokumentacje dla okreslonego numeru
   urzadzenia (np. okreslonego numeru kotla)

   -C <filename> - nazwa systemowego pliku konfiguracyjnego
   (domyslnie /etc/szarp/szarp-plc_config)

   -c <filename> - nazwa pliku konfiguracyjnego uzytkownika
   (domyslnie /home/jj/.szarp-plc)

   -p <filename> - nazwa pliku XML dla draw3 (domyslnie packs.xml)

   Brak parametrow - wyswietl pomoc

            
Wywołanie programu z parametrem:
$ ./docgen.pl weze
            
spowoduje utworzenie dokumentacji programu technologicznego oznaczonego przedrostkiem weze na podstawie plików źródłowych: wezewyk.c oraz wezedefi.h. Pliki źródłowe muszą znajdować się w tym samym katalogu, z którego został wywołany skrypt docgen. Plik wyjściowy przyjmuje nazwę wezewyk.doc.

Możliwe jest również generowanie dokumentacji z programu, który jest wspólny dla wielu urządzeń (np. dla wielu kotłów) i jest parametryzowany przy użyciu dyrektyw #ifdef oraz #define postaci:

#ifdef XXXX_y
            
gdzie XXXX jest dowolnym identyfikatorem, a y jest numerem urządzenia, innym dla każdego z urządzeń. W takim przypadku przy wywołaniu skryptu docgen należy podać parametr -n y, aby wygenerować dokumentację dla urządzenia numer y. Plik wynikowy przyjmie w tym wypadku nazwę prefixwyk_y.doc.