Creating table of contents of HTML document

On or about 5/18/09 9:52 AM, thus spake "Kirk McElhearn"
<kirkmcelhearn.com>:

> I'm working on some documentation in HTML, using BBEdit, and I'd
> really like to be able to whip up a table of contents quickly. As I'm
> going to be doing a bunch of manuals in HTML, I'd like to know if
> there's any trick to create a ToC based on headers in a document,
> preferably with BBEdit, but I'd be happy with any tool.

If you mean a Toc listing headers (h1, h2, h3 tags) at the top of the same
document, far and away the simplest approach is using XSLT.

If you mean a Toc *page* (a single page consisting of links to each of the
other pages in the document), you could write a script that generates the
page, or if this documentation is intended for Help Viewer, the Help API
includes a pseudo-tag that does this for you. m.

Text menu - Process lines containing... - Copy to clipboard h1 (or whatever) will give you a list of your headings, which can be edited in the Scratchpad to a list with links.You need to have given each heading a named anchor (link) first.

On Tue, May 19, 2009 at 04:52, Kirk McElhearn <kirkmcelhearn.com> wrote:
> I'm working on some documentation in HTML, using BBEdit, and I'd
> really like to be able to whip up a table of contents quickly. As I'm
> going to be doing a bunch of manuals in HTML, I'd like to know if
> there's any trick to create a ToC based on headers in a document,
> preferably with BBEdit, but I'd be happy with any tool.

I have done this in the past with an Applescript

* use BBEdit Process lines containing to grab the h2 (or whatever) lines
* put that text in a new document
* turn those lines into links
* put the result in your selected position in the source document.

Now, I'd be very happy to give you my Applescript as a starting point,
*if only I could find it*! Sigh.

I can keep looking, if you're interested. I last used it only a month
or two ago. Mail me off-list if you'd like me to search more.

Cheers,

Miraz

On May 18, 2009, at 12:52 PM, Kirk McElhearn wrote:

> I'm working on some documentation in HTML, using BBEdit, and I'd
> really like to be able to whip up a table of contents quickly. As I'm
> going to be doing a bunch of manuals in HTML, I'd like to know if
> there's any trick to create a ToC based on headers in a document,
> preferably with BBEdit, but I'd be happy with any tool.

Dreamweaver has a site map feature that organizes by heirarchy - it's
very helpful in building a ToC. But for this to work most effectively
for this task, your site should be organized in sub folders for
sections, and the pages should all have appropriate title tags - you
can choose View -- Show Page Titles. You can edit the titles while
you are in this view.

You can also isolate particular pages and choose View -- View As
Root, and the page will appear as a top level page.

If the links on pages are too distracting, you can do View -- Show/
Hide Links.

HTH,

Marilyn

On May 19, 2009, at 9:54 AM, Matt Neuburg wrote:

>> I'm working on some documentation in HTML, using BBEdit, and I'd
>> really like to be able to whip up a table of contents quickly. As I'm
>> going to be doing a bunch of manuals in HTML, I'd like to know if
>> there's any trick to create a ToC based on headers in a document,
>> preferably with BBEdit, but I'd be happy with any tool.
>
> If you mean a Toc listing headers (h1, h2, h3 tags) at the top of
> the same
> document, far and away the simplest approach is using XSLT.

Yea, but XSLT is not a tool, and a quick glance suggests that I'd have
a lot of reading to do to be able to accomplish what I want. I'm
looking for a simple solution, if one exists. If I have to change my
code to XHTML, that would not be simple.


Kirk

On Tue, May 19, 2009 at 5:40 PM, Kirk McElhearn <kirkmcelhearn.com> wrote:
>
> On May 19, 2009, at 9:54 AM, Matt Neuburg wrote:
>
>>> I'm working on some documentation in HTML, using BBEdit, and I'd
>>> really like to be able to whip up a table of contents quickly. As I'm
>>> going to be doing a bunch of manuals in HTML, I'd like to know if
>>> there's any trick to create a ToC based on headers in a document,
>>> preferably with BBEdit, but I'd be happy with any tool.
>>
>> If you mean a Toc listing headers (h1, h2, h3 tags) at the top of
>> the same
>> document, far and away the simplest approach is using XSLT.
>
> Yea, but XSLT is not a tool, and a quick glance suggests that I'd have
> a lot of reading to do to be able to accomplish what I want. I'm
> looking for a simple solution, if one exists. If I have to change my
> code to XHTML, that would not be simple.

It's been a while since I paid attention to such things, but isn't
XHTML 1.0 identical to strict HTML 4.0? As long as your HTML source is
fairly regular, it shouldn't be a big problem, I think.

I haven't done much with it, but XSLT really isn't that bad to pick
up. There are good examples & tutorials out there, and many of them
even use this exact problem as an example -- generating a table of
contents from HTML source. Pasting the first handful of decent looking
ones:

http://www.w3schools.com/xsl/ [<-- has good online interactive
tutorial to practice with]
http://www.stylusstudio.com/xsllist/200403/post40880.html
http://www.dpawson.co.uk/xsl/sect2/N7402.html
http://www.biglist.com/lists/xsl-list/archives/200702/msg00670.html
http://wdvl.internet.com/Authoring/Languages/XML/PracticalXML/practicalXML2_2.html


--
Chris Devers

At 23:33 -0700 UTC, on 2009-05-19, Chris Devers wrote:

> On Tue, May 19, 2009 at 5:40 PM, Kirk McElhearn <kirkmcelhearn.com> wrote:
>>
>> On May 19, 2009, at 9:54 AM, Matt Neuburg wrote:
>>
>>>> I'm working on some documentation in HTML, using BBEdit, and I'd
>>>> really like to be able to whip up a table of contents quickly. As I'm
>>>> going to be doing a bunch of manuals in HTML, I'd like to know if
>>>> there's any trick to create a ToC based on headers in a document,
>>>> preferably with BBEdit, but I'd be happy with any tool.
>>>
>>> If you mean a Toc listing headers (h1, h2, h3 tags) at the top of
>>> the same
>>> document, far and away the simplest approach is using XSLT.

Agreed. Although it probably depends somewhat on the aim:
- are we talking about generating a TOC per single HTML document?
- are we talking about generating a static TOC, or having it created
dynamically upon opening the document? (Web browsers, not IE, by now have
reasonable XSLT 1.0 support built right in; if IE can be ignored, I'd
definitely use xslt.)
- are we talking about some variant?

And for all applies:
- should TOC entries be merely textual, or hyperlink to the content?
- should the TOC be a new document? HTML too?
- should the TOC become part of the input document?
- etc.

So maybe a better answer is "it depends" :)

[...]

> It's been a while since I paid attention to such things, but isn't
> XHTML 1.0 identical to strict HTML 4.0?

Stictly speaking, not in the least. XHTML is a definition of HTML 4 in XML.
So it's a completely different beast. However, converting HTML 4 to XHTML 1
isn't much work -- assuming the HTML isn't the usual mess ;) Mostly boils
down to ensuring all elements are closed, and all names are lower case.


--
Sander Tekelenburg, <http://www.euronet.nl/~tekelenb/>

On or about 5/19/09 2:40 PM, thus spake "Kirk McElhearn"
<kirkmcelhearn.com>:

>
> On May 19, 2009, at 9:54 AM, Matt Neuburg wrote:
>
>>> I'm working on some documentation in HTML, using BBEdit, and I'd
>>> really like to be able to whip up a table of contents quickly. As I'm
>>> going to be doing a bunch of manuals in HTML, I'd like to know if
>>> there's any trick to create a ToC based on headers in a document,
>>> preferably with BBEdit, but I'd be happy with any tool.
>>
>> If you mean a Toc listing headers (h1, h2, h3 tags) at the top of
>> the same
>> document, far and away the simplest approach is using XSLT.
>
> Yea, but XSLT is not a tool

I'm not sure what that means. XSLT is very much a tool in my toolbox (and
xsltproc is my command-line access to it).

> and a quick glance suggests that I'd have
> a lot of reading to do to be able to accomplish what I want. I'm
> looking for a simple solution, if one exists. If I have to change my
> code to XHTML, that would not be simple.

I guess I think this *is* simple. XHTML is trivially HTML 4 with tag
closures ("<br />" instead of "<br>"). If I want a linked table of contents
at the start of a Web page, I just throw the appropriate XSLT at it as the
last stage of the page construction workflow.

I've posted a movie:

   http://www.apeth.com/toc.mov

I maintain my Web pages using John Gruber's Markdown. The movie shows you a
typical page - notice that there is no table of contents. Then I transform
the page into HTML, passing thru XHTML and XSLT to get a Web page with a
table of contents.

The construction kit use here is my own RubyFrontier, but *any* decent Web
page construction kit (Dreamweaver, BBEdit, etc.) will let you pass thru an
XSL transform as part of the creation of the page. It is a *standard* tool.
m.

I think it's pretty clear that XSLT is the right tool (or at least a
right tool) for the job.

But that is only the case quickly for one already familiar with its
use. I don't think for someone who isn't that it would be 10 minute's
reading and a couple of experiments.

(Well, except perhaps for a friend at MIT. But he was the subject of a
statement by the head of Naval Research Lab to a congressional
committee to the effect that "having [this guy] come to work for us
after college justified all the money we have spent on coop students
over all the years we've had coop students".)

  --John

On May 21, 2009, at 1:22 AM, Matt Neuburg wrote:

> The construction kit use here is my own RubyFrontier, but *any*
> decent Web
> page construction kit (Dreamweaver, BBEdit, etc.) will let you pass
> thru an
> XSL transform as part of the creation of the page. It is a
> *standard* tool.

It seems that the learning curve is quite steep for what I need...


Kirk

In BB Edit all you have to do is: write your page Markup> utilities> translate to translate text to html Go Markup> Misc> index Document 'et voila' a table of contents at the top of the page based on your headings.. XSLT and stuff is nice but not needed here

BB Edit is a great bit of kit by the way and makes life easier..

On Jun 3, 2009, at 8:12 PM, Geezer wrote:

> In BB Edit all you have to do is: write your page Markup> utilities>
> translate to translate text to html Go Markup> Misc> index Document
> 'et voila' a table of contents at the top of the page based on your
> headings.. XSLT and stuff is nice but not needed here


Well, the first thing totally borks the document, but the second is
more or less what I was looking for. Thanks!

Kirk

On or about 6/3/09 11:12 AM, thus spake "Geezer"
<andrew.williamsonsussexdowns.ac.uk>:

> In BB Edit all you have to do is ... Markup> Misc> index Document

Mmmmm, not really. On my machine, on my Web pages, that command mostly
generates nonsense (unless you do a lot more preparation by hand). m.

On Jun 4, 2009, at 9:23 AM, Matt Neuburg wrote:

>>
>> In BB Edit all you have to do is ... Markup> Misc> index Document
>
> Mmmmm, not really. On my machine, on my Web pages, that command mostly
> generates nonsense (unless you do a lot more preparation by hand). m.

Really? For me it adds IDs to Hs then creates a new page with an
"index" - close to a ToC - of those Hs.


Kirk