DRAFT Documentation System Proposal

From: Calvin Arndt (calarndt@yahoo.com)
Date: Fri Mar 08 2002 - 20:51:17 GMT

  • Next message: Michael D. Pritchett: "commit - RTF Memory Error w/ Images"

    While researching the needs of the documentation build system I have
    come across some issue's that could well be resolved if we adopt some
    ground rules for abi documentation.

    The purpose of the the doc build system (as I see it today) would be to
    build the HTML help system from native AbiWord doc's. This puts those
    documents in more of a SOURCE code role, than just a documentary role.

    To build the html documentation I need to be able to reliably retrieve
    three pieces of information from the "source abi docs.

    1.) Link information (which docs links to which)
    2.) Link Title information
    3.) Authoring Information

    Currently I have a system working which ALMOST reliably gets #1. Almost
    is due to inconsistencies in the source abi docs...

    Seems that abi doesn't always create links in the same way. this can be
    viewed comparing the toplevel index.abw to the index.abw in the
    problems dir and also comparing those 2 files with the link in

    (the link in credits.abw has a # symbol in it) (which is a bookmark

    I currently have no method for retrieving either 2 or 3 but both should
    be easily retrievable...

    Some things thing that could automatically be created on the fly:

    Index pages (even the top!)
    hmtl footer's for each dir
    html headers for each dir
    I think that by combining two abi functions we could create a pretty
    nice (automatically generated) html help system where the documenters
    would only need to be concerned with their source documents not the
    html stuff...

    If we add 2 bookmarks in the source docs:


    I can use the text of these bookmarks to generate the html fields:

    Copyright statement

    if we added:


    this text could be use to build the text of the index pages...

    Doing all of this would allow a documentor to...

    add a category by just adding a newcategory.abw to the toplevel dir
    ie. in en-US

    If required he could add a new dir under en-US for multilevel stuff
    whats currently there...

    To conclude:
    The only real issues here are that we agree on a format for the
    bookmarks and that abi actually create the link without the # symbol
    so I can tell a link from a bookmark

    currently if you
    Abi adds the link while giving you the error (DOC DOESN'T EXIST)
    but the link created is
    instead of:
    (which may just mean I don't know how to do it right)
    The point is links don't contain # bookmarks do...

    Calvin Arndt

    Do You Yahoo!?
    Try FREE Yahoo! Mail - the world's greatest free email!

    This archive was generated by hypermail 2.1.4 : Fri Mar 08 2002 - 15:57:13 GMT