Asciidoctor table of contents

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Asciidoctor table of contents

jimmi
Hi there,

Loving Awestruct & Asciidoctor :-) In the process of migrating some of our engineering documentation over to it, I'm struggling to generate a table of contents. Using straight Asciidoctor, just adding the :toc: attribute works brilliantly, but I get no toc generated when using with Awestruct.

Any tips?

Thanks,
Jimmi

NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

LightGuard
Administrator
It's probably a bug, also which version of awestruct are you using?


On Mon, Apr 22, 2013 at 12:38 PM, Jimmi Dyson <[hidden email]> wrote:
Hi there,

Loving Awestruct & Asciidoctor :-) In the process of migrating some of our engineering documentation over to it, I'm struggling to generate a table of contents. Using straight Asciidoctor, just adding the :toc: attribute works brilliantly, but I get no toc generated when using with Awestruct.

Any tips?

Thanks,
Jimmi

NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.



--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

mojavelinux
In reply to this post by jimmi
Jimmi,

I'm thrilled to hear you are enjoying this "static" duo. That's great news.

When I was putting together the asciidoctor.org site, I too ran into the missing toc problem. Awestruct runs Asciidoctor in embedded mode (i.e., :header_footer => false). In embedded mode, Asciidoctor does not output a toc, regardless of whether the :toc: attribute is present. Asciidoctor does this intentionally to conform with AsciiDoc.

That explanation doesn't answer the question, though. The question is, how do we add the toc to the page. The answer is a feature that isn't yet implemented in Asciidoctor, manual toc placement [1]. Once it's implemented, you place the toc::[] macro at the point you want the toc inserted. Anywhere you put it, it will be included in the page generated by Awestruct.

 = Document Title
 Author Name

 toc::[]

 This document...

I'm going to see if I can squeeze in this feature for the 0.1.2 release scheduled to go out tomorrow.

-Dan




On Mon, Apr 22, 2013 at 12:38 PM, Jimmi Dyson <[hidden email]> wrote:
Hi there,

Loving Awestruct & Asciidoctor :-) In the process of migrating some of our engineering documentation over to it, I'm struggling to generate a table of contents. Using straight Asciidoctor, just adding the :toc: attribute works brilliantly, but I get no toc generated when using with Awestruct.

Any tips?

Thanks,
Jimmi

NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

mojavelinux
Looks like this is going to make it for 0.1.2. All I have left is to create some tests and commit. To use it in Awestruct, all you'll have to do is update to Asciidoctor 0.1.2 as soon as it's released.

-Dan


On Mon, Apr 22, 2013 at 9:45 PM, Dan Allen <[hidden email]> wrote:
Jimmi,

I'm thrilled to hear you are enjoying this "static" duo. That's great news.

When I was putting together the asciidoctor.org site, I too ran into the missing toc problem. Awestruct runs Asciidoctor in embedded mode (i.e., :header_footer => false). In embedded mode, Asciidoctor does not output a toc, regardless of whether the :toc: attribute is present. Asciidoctor does this intentionally to conform with AsciiDoc.

That explanation doesn't answer the question, though. The question is, how do we add the toc to the page. The answer is a feature that isn't yet implemented in Asciidoctor, manual toc placement [1]. Once it's implemented, you place the toc::[] macro at the point you want the toc inserted. Anywhere you put it, it will be included in the page generated by Awestruct.

 = Document Title
 Author Name

 toc::[]

 This document...

I'm going to see if I can squeeze in this feature for the 0.1.2 release scheduled to go out tomorrow.

-Dan




On Mon, Apr 22, 2013 at 12:38 PM, Jimmi Dyson <[hidden email]> wrote:
Hi there,

Loving Awestruct & Asciidoctor :-) In the process of migrating some of our engineering documentation over to it, I'm struggling to generate a table of contents. Using straight Asciidoctor, just adding the :toc: attribute works brilliantly, but I get no toc generated when using with Awestruct.

Any tips?

Thanks,
Jimmi

NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

jimmi
That's brilliant news Dan - looking forward to the new release.

It would be great to be able to use this kind of macro in an Awestruct layout as well - e.g. an Awestruct docs layout that has the toc macro in a sidebar. Would a helper be the right way to go about adding that? I guess I could parse the page content to put it in? I'll give that a go.

Thanks again,
Jimmi
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

mojavelinux
And here it is in action!


To answer your other question, yes, the idea is to store the Asciidoctor Document object in the Awestruct page context. That way, you can get any information out of you need, including the toc structure, and put the toc anywhere you want in the layout. That reminds me, I need to file and issue for that enhancement.


-Dan


On Wed, Apr 24, 2013 at 6:51 AM, jimmi <[hidden email]> wrote:
That's brilliant news Dan - looking forward to the new release.

It would be great to be able to use this kind of macro in an Awestruct
layout as well - e.g. an Awestruct docs layout that has the toc macro in a
sidebar. Would a helper be the right way to go about adding that? I guess I
could parse the page content to put it in? I'll give that a go.

Thanks again,
Jimmi



--
View this message in context: http://talk-archive.awestruct.org/Asciidoctor-table-of-contents-tp239p244.html
Sent from the Awestruct Talk mailing list archive at Nabble.com.

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

jimmi
Looking good. I've written a TOC generator helper passing in the generated page content & parsing it for headers (Ruby beginner right now so please excuse any obvious mistakes - or even better tell me where it could be improved :-)):

def toc(content, headers_selector='h1,h2,h3')
    doc = Nokogiri::HTML::Document.parse(content)
    builder = Nokogiri::XML::Builder.new do |toc|
        toc.ul {
            doc.css(headers_selector).each do |header|
                toc.li {
                    toc.a(:href => "##{header['id']}") {
                        toc.text header.content
                    }
                }
            end
        }
    end
    builder.to_xml :save_with => Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
end

Using in the layout like:

div=toc(content, 'h1,h2')

Thanks,
Jimmi


On 26 April 2013 08:51, Dan Allen <[hidden email]> wrote:
And here it is in action!


To answer your other question, yes, the idea is to store the Asciidoctor Document object in the Awestruct page context. That way, you can get any information out of you need, including the toc structure, and put the toc anywhere you want in the layout. That reminds me, I need to file and issue for that enhancement.


-Dan


On Wed, Apr 24, 2013 at 6:51 AM, jimmi <[hidden email]> wrote:
That's brilliant news Dan - looking forward to the new release.

It would be great to be able to use this kind of macro in an Awestruct
layout as well - e.g. an Awestruct docs layout that has the toc macro in a
sidebar. Would a helper be the right way to go about adding that? I guess I
could parse the page content to put it in? I'll give that a go.

Thanks again,
Jimmi



--
View this message in context: http://talk-archive.awestruct.org/Asciidoctor-table-of-contents-tp239p244.html
Sent from the Awestruct Talk mailing list archive at Nabble.com.

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597



NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor table of contents

mojavelinux
Jimmi,

That's certainly a sound approach, one that we took when creating the Arquillian website in the pre-AsciiDoc days.

Another interim approach is to just invoke Asciidoctor directly on the source document. You can access the source document from the variable page.relative_source_path (or something similar). If you pass that to the Asciidoctor load API, it will give you a Document object, which you can walk to get the sections.

doc = Asciidoctor.load_file(page.relative_source_path) <= double check that variable reference


Asciidoctor is absurdly fast (esp in Ruby scale), so you wouldn't notice any performance hit from parsing the document again. (In fact, Awestruct parses documents several times already, so it's more like the 6th time parsing it).

-Dan


On Fri, Apr 26, 2013 at 2:34 AM, Jimmi Dyson <[hidden email]> wrote:
Looking good. I've written a TOC generator helper passing in the generated page content & parsing it for headers (Ruby beginner right now so please excuse any obvious mistakes - or even better tell me where it could be improved :-)):

def toc(content, headers_selector='h1,h2,h3')
    doc = Nokogiri::HTML::Document.parse(content)
    builder = Nokogiri::XML::Builder.new do |toc|
        toc.ul {
            doc.css(headers_selector).each do |header|
                toc.li {
                    toc.a(:href => "##{header['id']}") {
                        toc.text header.content
                    }
                }
            end
        }
    end
    builder.to_xml :save_with => Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
end

Using in the layout like:

div=toc(content, 'h1,h2')

Thanks,
Jimmi


On 26 April 2013 08:51, Dan Allen <[hidden email]> wrote:
And here it is in action!


To answer your other question, yes, the idea is to store the Asciidoctor Document object in the Awestruct page context. That way, you can get any information out of you need, including the toc structure, and put the toc anywhere you want in the layout. That reminds me, I need to file and issue for that enhancement.


-Dan


On Wed, Apr 24, 2013 at 6:51 AM, jimmi <[hidden email]> wrote:
That's brilliant news Dan - looking forward to the new release.

It would be great to be able to use this kind of macro in an Awestruct
layout as well - e.g. an Awestruct docs layout that has the toc macro in a
sidebar. Would a helper be the right way to go about adding that? I guess I
could parse the page content to put it in? I'll give that a go.

Thanks again,
Jimmi



--
View this message in context: http://talk-archive.awestruct.org/Asciidoctor-table-of-contents-tp239p244.html
Sent from the Awestruct Talk mailing list archive at Nabble.com.

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597



NOTICE: This message contains privileged and confidential information intended only for the addressee. If you have received this message in error you must not disseminate, copy or take action on it; please notify [hidden email] Opinions expressed in this message are those of the sender and do not necessarily represent those of Specsavers. Although this e-mail and any attachments are believed to be virus free, e-mail communications are not 100% secure and Specsavers makes no warranty that this message is secure or virus free. All references to Specsavers means Specsavers Optical Superstores Limited, a company limited by shares and registered in England under number 1721624 of Forum 6, Parkway, Solent Business Park, Whiteley, Fareham, Hampshire, PO15 7PA. Nothing in this transmission shall or shall be deemed to constitute an offer or acceptance of an offer or otherwise have the effect of forming a contract by electronic communication. Your name and address may be stored to facilitate communication.


.



--
Dan Allen
Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597