in reply to Re^2: The problem of documenting complex modules.
in thread The problem of documenting complex modules.

Excellent thread, BrowserUK ... very thought-provoking throughout, and showered with up-votes.

I definitely agree with you that POD is too limiting ... except for the fact that it can be, and to the extent that it is, embedded within or alongside the Perl code that it refers to, and therefore also subject to change control.   It is, therefore, a very special purpose form of documentation, and not good enough for the entire system.   (But, one might suggest, really not intended so to be.)

For most documentation purposes, I use the DocBook format (or, in some cases, another proprietary format such as the one you encountered Intel using ...), and the XMLMind XML Editor (XXE) as the writing tool of choice.   (I’ve never purchased the commercial version.)   The documentation is written in XML format, but the tool formats it on-the-fly so that you are seeing it, and writing it, in a WYSIWYG-formatted view.

These are “semantic markup” techniques:   for instance, the definition of a <function> includes subtags (and subtags of these) which describe what the various elements are ... arguments, return values, description, errors thrown ... not how they will look on the page.   From this XML-database, which is always known to conform to the specified schema, information can be selected, extracted, and then formatted into a variety of deliverables, either using (commercial ...) XXE facilities, or third-party XML tools like Saxon.

There are also converters which can scan for and extract POD documentation, although they oblige the POD-writer to adhere to certain “markup” conventions in order to convey usable semantic meaning.

  • Comment on Re^3: The problem of documenting complex modules.

Replies are listed 'Best First'.
Re^4: The problem of documenting complex modules.
by Anonymous Monk on Jul 06, 2015 at 20:20 UTC
    And an equally excellent reply, sundialsvc4 ... very rich in font variants and punctuation.

    I too definitely agree about this limitations of POD ... except for when POD offers you too much and does everything. Embedded Perl within Perl is the answer. (But as you might suggest ... what is the question?)

    Lo! Behold!

    These techniques: underline and boldly emphasize where no post has gone.

    Clears up any ambiguity as to where to start learning.