From: Calvin Arndt (calarndt@yahoo.com)
Date: Fri Mar 08 2002 - 20:51:17 GMT
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
credits.abw
(the link in credits.abw has a # symbol in it) (which is a bookmark
right?)
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:
#author
#title
I can use the text of these bookmarks to generate the html fields:
<title>
Copyright statement
if we added:
#description
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
like
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
Insert>hyperlink>newlink.html[enter]
Abi adds the link while giving you the error (DOC DOESN'T EXIST)
but the link created is
#newlink.html
instead of:
newlink.html
(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!
http://mail.yahoo.com/
This archive was generated by hypermail 2.1.4 : Fri Mar 08 2002 - 15:57:13 GMT