März 2008 Archive

Bei vielen Projekten will man die Dokumentation, die in den eigenen Modulen und Skripten (hoffentlich!) haufenweise als POD vorhanden ist, nach HTML wandeln und sich so eine lokale Dokumentation erstellen.

Mit welchen Modulen / Werkzeugen erstellt Ihr Euer HTML (oder PDF oder ...)?

Ich habe gerne Pod::ProjectDocs verwendet, da das alles auf einen Rutsch erledigt. Nur das optionale Syntax Highlighting geht derzeit nicht, da Syntax::Highlight::Universal sich nicht compilieren lässt.

Nun ist mir Pod::Classdoc mit mkprojdocs aufgefallen, das zusätzlich auch noch Javadoc-ähnliche Formatierung erlaubt. Damit lassen sich dann relativ übersichtlich alle Ein/Ausgabeparameter auflisten. Bisher habe ich das gerne mit =item-Listen gemacht, aber dann wird der POD-Quelltext schnell unübersichtlich. Hierfür Javadoc zu nutzen erscheint also eine ganz brauchbare Lösung zu sein.

Es gibt ansonsten noch dutzende POD-Parser und -Konverter im CPAN; Pod::Simple mit Pod::Simple::HTMLBatch sieht evtl. auch brauchbar aus. Aber Pod::ProjectDocs bzw. Pod::Classdoc mit mkprojdocs scheint mir das einzige zu sein, dass ohne eigene Basteleien sofort funktioniert.

Update: Pod::POM::Web habe ich ganz vergessen zu erwähnen, mit dem man die Dokumentation zu allen lokal installierten Modulen im Browser nutzen kann. Eine sehr praktische Sache, aber auch nicht immer geeignet.

Damit ich es nicht wieder vergesse (und beim nächsten mal die Suchmaschinen mit den falschen Suchbegriffen füttere):

Um den physikalischen Speicherplatz einer Datenbank, Tabelle, Indexes usw. zu berechnen stellt PostgreSQL einige Funktionen bereit: System Administration Functions.

Um zum Beispiel ergibt der folgende Query den auf der Festplatte belegten Speicher für die Tabelle sessions, inklusive Indexe, TOAST-Daten usw:  

db=> SELECT pg_total_relation_size('sessions');
 pg_total_relation_size 
------------------------
              563707904
(1 row)

Ohne total kann man sich auch nur den Speicherplatz für die Daten ohne Indexe und TOAST-Daten anzeigen lassen, ein Beispiel verkneife ich mir nun aber.

Und mit pg_size_pretty kann man sich das ganze auch menschenlesbar formatieren lassen:

SELECT pg_size_pretty(pg_total_relation_size('sessions'));
 pg_size_pretty 
----------------
 538 MB
(1 row)

Auch der von einem Index belegte Speicherplatz lässt sich so herausfinden: 

db=> SELECT pg_size_pretty(pg_total_relation_size('sessions_pkey'));
 pg_size_pretty 
----------------
 72 MB
(1 row)

Alles in allem ganz schön viel für ein paar gammelige Sessiondaten: Es wurden einfach zu viele angelegt, zum Beispiel an Stellen, an denen nur eventuell vorhandene ausgelesen werden sollten.

Man kann sich aber auch ausgeben lassen, wieviel Speicher eine Spalte benötigt. Hier sieht man dann auch gut, welchen Effekt die Kompression von langen Texten bei Postgres hat:

odem=> SELECT uri, length(text), pg_column_size(text) FROM main_data;
                     uri                     | length | pg_column_size 
---------------------------------------------+--------+----------------
 /insert_coin/medien/boese.html              |  17964 |          10324
 /insert_coin/medien/schluesse.html          |  23644 |          13588
 /insert_coin/experiment/protokoll.html      |   8331 |           5070
 /insert_coin/experiment/manipulationen.html |  23079 |          12601
 /insert_coin/vorwort.html                   |   2841 |           2841
 /insert_coin/experiment/aenderung.html      |   6107 |           3620
 /insert_coin/medien/at-bombe.html           |  28267 |          15941
 /insert_coin/impressum.html                 |    590 |            594

 [...]
 

Weitere Funktionen sind in der Postrgres-Dokumentation aufgeführt, zum Beispiel zum Berechnen des Gesamtspeicherverbrauchs einer Datenbank.

(dank an #postgresql-de (IRC) und ads)