[dbdoclet] book assembly, duplicate anchor resolution

Hi Michael and all!

First post on this list.

Have to start by saying dbdoclet is an amazing application. It's 
churning out incredible stuff for me, as the engine for a docbook 
documentation system behind a low-user-overhead wiki. Basically, I 
have a few feature/tweak requests that I thought I would submit here, 
for the betterment of all, and perhaps the betterment of dcdoclet as 
well!

1. Resolving identical anchors in source html

Many times when users use templates or includes they don't update all 
the details, and sometimes anchor id's, etc. can wind up duplicates. 
When rendering out the DocBook, those errors can make publishing to 
pdf via FOP stop dead in it's tracks. I know that's currently the 
desired behavior, to allow for troubleshooting, etc.

Indeed, the first question is why the users don't eliminate them from 
the source html... however in our environment that 'source' html is 
actually an assembled set of chapters in a wiki, and grouped by 
include. So, we do make a practice of 'unique-ifying' the names, but 
it takes a lot of oversight.

Perhaps a means of at least auto-'unique-ifying' the anchor id's 
would allow the document to process through as pdf, even if it did 
cause anchor misdirection.

In thinking about the problem, it led me to...

2. Perhaps, the most ideal, functional and flexible solution would be 
chunking of source html by dbdoclet into a book.

In other words - allowing strings of <chapter> or <article> (or even 
<sect?>) to be defined by simply passing multiple html files one 
after another on the command line:

html2db -i file1.htm file2.htm file3.htm file4.htm Appendix.html, 
etc. ? Did I go too far with Appendix?

resulting in
<article>article 1
<article>article 2
  or
<chapter>chapter 1
<article>chapter 2
, etc.

If this were possible, it seems to me that a natural 
consequence/requirement would be that their individual anchors (even 
if named identically in the source html) could be parsed, made 
unique, but not lose their 'direction' within the final doc...

What do you good folks think?

Micki Kaufman

At 9:23 PM +0200 10/15/03, Michael Fuchs wrote:
>Here you can subscribe:
>http://www.dbdoclet.org/MailingList.html
>
>Bye
>   Michael
>
>>Thanks for the response!
>>
>>   I would love to continue the conversation there. I found it very
>>difficult to find the list subscribe (I'm a mailman aficionado, so I
>>have no excuse).
>>
>>Can you pass along a link, I'll subscribe and post?
>>
>>Thanks!
>>Micki
>>
>>At 8:58 PM +0200 10/15/03, Michael Fuchs wrote:
>>>Hello Micki,
>>>
>>>thank you for your proposals.
>>>
>>>1. It is possible to create unique anchor names inside the resulting
>>>  docbook, but if you have two indentical anchor names the result will be
>>>  probably wrong, because all references will point to one of them in the
>>>  end. I thought it is better to leave the errors in the resulting docbook,
>>>  so it is easier to find the affected locations. Perhaps it is the best to
>>>  introduce a new property.
>>>
>>>2. Assembling a book is a nice idea. Any ideas how to do this?
>>>
>>>3. Can we continue the discussion at the dbdoclet mailing list? Perhaps
>>>anybody else is interested.
>>>
>>>Bye
>>>    Michael
>>>
>>>>FYI.
>>>>http://phpwiki.sourceforge.net/phpwiki/PhpWikiToDocBookAndPDF
>>>>
>>>>Thanks again, and let me know if you'd like to discuss the duplicate
>>>>anchorname issue.
>>>>
>>>>Micki
>>>>
>>>>>Hi there!
>>>>>
>>>>>Db doclet is now the power behind our documentation build process.
>>>>>
>>>>>Phenomenal job!
>>>>>
>>>>>I'm finding that a lot of my pages, when bundled together into a
>>>>>book, conflict due to identically-named anchors (usually holdovers
>>>>>from templates).
>>>>>
>>>>>If duplicate, named anchors are encountered, does it make sense for
>>>>>dbdoclet to uniquely rename them?
>>>>>
>>>>>Many thanks again for your great work.
>>>>>Micki
>>>
>>>--
>>>Dipl.-Ing.(FH) Michael Fuchs
>>>Tel. (0 81 61) 14 41 66
>>>Fax. (0 81 61) 14 05 21
>>>Mobil 0 16 07 84 53 84
>>>EMail mfuchs@xxxxxxxxxxxxxxxxxxxx
>  >>URL http://www.michael-a-fuchs.de
>
>--
>Dipl.-Ing.(FH) Michael Fuchs
>Tel. (0 81 61) 14 41 66
>Fax. (0 81 61) 14 05 21
>Mobil 0 16 07 84 53 84
>EMail mfuchs@xxxxxxxxxxxxxxxxxxxx
>URL http://www.michael-a-fuchs.de


-- 

Micki
mailto:micki001@xxxxxxxxxxxxxx

Other related posts: