From: David Chart (linux@dchart.demon.co.uk)
Date: Fri Mar 08 2002 - 21:15:08 GMT
On Fri, 2002-03-08 at 20:51, Calvin Arndt wrote:
> 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.
Yes, this is what we're after.
>
> 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
Actually, Abi always creates them with #. In credits.abw, I forgot to
delete the # in a text editor.
>
> I currently have no method for retrieving either 2 or 3 but both should
> be easily retrievable...
They're both in the .info files, now, and thus trivially retrievable (I
hope).
The advantage of .info files is that it's easier to see the information
-- you don't have to call up the bookmark list.
>
> Some things thing that could automatically be created on the fly:
>
> Index pages (even the top!)
The index.html pages aren't indices. They're the default pages, so they
need to be written properly.
Actual indexes/site maps, OTOH, would be great and should be
autogenerated.
> hmtl footer's for each dir
> html headers for each dir
>
Yep, I think those could be done automatically.
> 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...
>
The .info files can do this bit, right? I think the separate files are
easier than bookmarks, if only because the bookmark dialog window is
quite small.
> 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...
>
At the moment, just adding the directory and a link in the top index.abw
has this effect.
> 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...
>
The way to do this is to open your .abw file in a text editor and delete
the # by hand. ;-)
David
-- David Chart
This archive was generated by hypermail 2.1.4 : Fri Mar 08 2002 - 16:21:15 GMT