I understand Eric’s difficulty in generating PDFs without the aid of an industrial-strength tech writer’s tool.
But I still find the documentation extremely difficult to use. No fault of Eric’s, it’s just an enormous amount of complexity to absorb.
Once I’ve read something and moved on, there is no easy way to go back and review it later. I need a map .
I think I have solved the problem as best I can without resorting to something like FrameMaker, my tool of choice for this kind of task. It would do the job quite nicely, but that’s pretty serious $$$. Surely, there must be a better way. And so…
In a previous life, I had a need to update a large number of files littered through a deeply nested filesystem, to add a boilerplate prologue to every source file in a collection of demonstration Java utilities I had written for an API Programmer’s Guide.
If you know Java, you know the file system for a Java project can be quite intricate.
Automation was my friend.
With a small expenditure of effort over the past day and half, I have updated that automated file-updater utility so that it reads each of the files in a TADS doc directory and creates index references from specially constructed anchor tags that I have added to the files.
I have attached that utility to this post; inside the ZIP is the .jar that does the heavy lifting, plus a copy of the Adv3Lite Library Manual that Eric includes in the Adv3Lite library distribution.
I have added anchor tags and run the indexer; if you unzip the bundle, you can point a browser at the manual’s index.htm file to see what the index looks like. It’s simple, not ideal, but does the job.
If you want to add your own anchor tags go ahead, then run the .bat file. If you want to point the utility at your own collection of files, without my anchor tags, you can do that, to.
Read the readme to find out how to do it, using the properties file in the resource directory.
The utility creates a file of index references, in the form of a list of links to the places in the doc that discuss the various topics I indexed. The utility then adds a link to this new file to the manual’s existing index.htm…
The good news is, it is quite easy to add an anchor tag to the HTML file whenever I encounter some topic that I think I may want to look up later. I can just edit the HTML file like this…
<a name="some_topic_idx">Some Topic</a>
…and run my index generator. As long as the anchor name value ends in _idx, the item will automatically appear in the index…
The bad news is, these tags won’t persist through a library update from Eric (unless he wants to add these anchor tags to his doc source files). But it’s better than nothing, especially now when I’ve just started absorbing the huge amount of technical detail contained in the docs.
Maybe by the time he does a doc update, I won’t be so desperate for a map.
tads3lite-indexer.zip (366 KB)