docbook-apps

  • 1.  Compact DocBook ?

    Posted 07-12-2010 08:37
    Dear all,

    [I hope this is on-topic for this list]

    I'm hoping to embed DocBook within some Java code (as comments). Along with
    some support utilities, this should allow embedding of documentation next to
    the code it describes. This is somewhat similar to JavaDoc, but:

    a. using DocBook vocabulary,

    b. to be included within end-user documentation.

    The thought of writing DocBook XML inside Java comments isn't appealing.

    So, does anyone know of a more compact markup for DocBook than XML (e.g.,
    RELAX-NG) ?

    Cheers,

    Paul.



  • 2.  Re: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 09:52
    On Mon, 12 Jul 2010 10:36:36 +0200
    Paul Millar <paul@astro.gla.ac.uk> wrote:

    > Dear all,
    >
    > [I hope this is on-topic for this list]
    >
    > I'm hoping to embed DocBook within some Java code (as comments).

    Think of it the other way round?
    Embed java code in Docbook?

    then you have a perfectly normal docbook document,
    from which you can extract java code to execute it
    and process into fully documented code!
    Tangle and weave are the ideas,
    Literate Programming the background.

    http://www.dpawson.co.uk/litprog/ may help.

    HTH




    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 3.  Re: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 11:20
    > then you have a perfectly normal docbook document,

    ... and you lose the ability to use of development tools like IDEs,
    you have to regenerate the sources every time you make a tiny change
    (which happens much more often than regenerating documentation),
    debuggers get confused, you need to set up a way to name your sources
    and map this to the filesystem, ...

    Unfortunately, this way of working works if the main thing you're
    writing is documentation with some toy examples in them (and even
    then, I personally just write scripts that embed pure source code into
    DocBook includes). It doesn't work for real development.

    cheers,
    Remko



  • 4.  Re: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 11:40
    On Mon, 12 Jul 2010 13:19:31 +0200
    Remko Tronçon <remko@el-tramo.be> wrote:

    > > then you have a perfectly normal docbook document,
    >
    > ... and you lose the ability to use of development tools like IDEs,
    > you have to regenerate the sources every time you make a tiny change
    > (which happens much more often than regenerating documentation),
    > debuggers get confused, you need to set up a way to name your sources
    > and map this to the filesystem, ...
    >
    > Unfortunately, this way of working works if the main thing you're
    > writing is documentation with some toy examples in them (and even
    > then, I personally just write scripts that embed pure source code into
    > DocBook includes). It doesn't work for real development.


    Doesn't work for you?
    yet you use xInclude... which could include files from your IDE?
    Odd, that sounds like a reasonable litprog way of doing it.

    Be assured, it does work for non trivial examples.

    regards


    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 5.  Re: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 11:44
    Remko Tronçon wrote:

    > Unfortunately, this way of working works if the main thing you're
    > writing is documentation with some toy examples in them (and even
    > then, I personally just write scripts that embed pure source code into
    > DocBook includes). It doesn't work for real development.

    Of couse it is not mainstream, but this method of writing software was
    successfully used on very complex software projects like TeX. So I would
    not just straightly deny this idea.

    --
    ------------------------------------------------------------------
    Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz
    ------------------------------------------------------------------
    Professional XML consulting and training services
    DocBook customization, custom XSLT/XSL-FO document processing
    ------------------------------------------------------------------
    OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
    ------------------------------------------------------------------




  • 6.  SV: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 11:15
    Another way to do it is to use regular JavaDoc and do the following:
    1 Generate html from java
    2 Generate DocBook from html
    We do something similar but our primary targets are wiki-pages.
    In our case we "mark" the interesting JavaDoc blocks with html
    -elements (actually they also have an id-attribute for future flexibility). In the html we extract these div-blocks and create the target of choice (wikipages).
    As a by-product we also generate a DocBook document where each selected class will become a chapter and these are enveloped by standard (DocBook) elements to create a complete document.

    Regards Lars

    -----Ursprungligt meddelande-----
    Från: Paul Millar [mailto:paul@astro.gla.ac.uk]
    Skickat: den 12 juli 2010 10:37
    Till: docbook-apps@lists.oasis-open.org
    Ämne: [docbook-apps] Compact DocBook ?

    Dear all,

    [I hope this is on-topic for this list]

    I'm hoping to embed DocBook within some Java code (as comments). Along with
    some support utilities, this should allow embedding of documentation next to
    the code it describes. This is somewhat similar to JavaDoc, but:

    a. using DocBook vocabulary,

    b. to be included within end-user documentation.

    The thought of writing DocBook XML inside Java comments isn't appealing.

    So, does anyone know of a more compact markup for DocBook than XML (e.g.,
    RELAX-NG) ?

    Cheers,

    Paul.

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
    For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org




  • 7.  Re: SV: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 11:47
    lars.bjerges@swedbank.se wrote:
    > Another way to do it is to use regular JavaDoc and do the following:
    > 1 Generate html from java
    > 2 Generate DocBook from html

    There is nice tools dbdoclet which can be used for generating DocBook
    from JavaDoc comments. I think that with some customization it could be
    used for what Paul asked in his original post.

    http://www.dbdoclet.org/

    --
    ------------------------------------------------------------------
    Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz
    ------------------------------------------------------------------
    Professional XML consulting and training services
    DocBook customization, custom XSLT/XSL-FO document processing
    ------------------------------------------------------------------
    OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
    ------------------------------------------------------------------




  • 8.  Re: [docbook-apps] Compact DocBook ?

    Posted 07-12-2010 15:13
    +--
    | I'm hoping to embed DocBook within some Java code (as
    | comments). Along with some support utilities, this should
    | allow embedding of documentation next to the code it describes.
    | This is somewhat similar to JavaDoc, but:
    |
    | a. using DocBook vocabulary,
    |
    | b. to be included within end-user documentation.
    |
    | The thought of writing DocBook XML inside Java comments isn't appealing.
    +--

    Why not turn the whole process inside out?

    http://www.nmt.edu/~shipman/soft/litprog/

    For several years now, all my serious coding is done in
    "lightweight literate programming" (LLP) style. The idea is to
    have the documentation contain the program, not vice versa.

    Here's how I develop code nowadays.

    1. Write up the external interface in DocBook.

    2. Document the "big picture" parts of the design, also in
    DocBook. For a small project, this can be the same document
    as the external spec; for substantial projects, I'll start a
    separate "Internal Maintenance Specification".

    3. Write the program as a continuous narrative with embedded
    code blocks contained within DocBook <programlisting>
    elements. To distinguish example code blocks from live
    code blocks, I used the extension 'role' attribute to
    route the code into the files from which it will be run
    or compiled. Here's an example:

    ================================================================
    <para>
    The first lines make this script self-executing, and point
    back to this documentation:
    </para>
    <programlisting role='outFile:myscript.py'>
    #!/usr/bin/env python
    # myscript.py: This script...
    # For documentation, see http://... <- HTML output from DocBook
    import sys
    ...
    </programlisting>
    ----------------------------------------------------------------

    Writing a script to extract the source code files took me about
    an hour, including all documentation. It's trivial in any
    language with a decent XML toolset; I used Python and lxml.

    Note that you can include any number of files in any number of
    languages. One drawback of JavaDocs is that it works only
    with Java. Sometimes the project includes non-Java files,
    such as CSS stylesheets; why not include them in literate
    form as well?

    See the URL above for the code extractor and several dozen
    complete projects done in this style. The originator of
    Lightweight Literate Programming is my colleague Dr. Allan
    Stavely, based on the classic 1980s-era literate programming idea
    from Dr. Don Knuth.

    Best regards,
    John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
    Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john
    ``Let's go outside and commiserate with nature.'' --Dave Farber