how to setup documents for BOTH texthtml5) and slide (reveal.js) output?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

how to setup documents for BOTH texthtml5) and slide (reveal.js) output?

gernotstarke
I want it all :-)
For software-archtitecture documentation I'd like to generate both html5 AND slide output...
(slides containing less content than html5, of course)

Any experience or ideas how to achieve that?

example of such content:
https://github.com/aim42/htmlsanitycheck, documentation subproject
Reply | Threaded
Open this post in threaded view
|

Re: how to setup documents for BOTH texthtml5) and slide (reveal.js) output?

mojavelinux
Administrator
Gernot,

This is something that Jason Porter has been contemplating a lot recently. He started a similar thread a while back (still ongoing).


What I would recommend is to modify the deck.js or reveal.js backends from https://github.com/asciidoctor/asciidoctor-backends so that they pick and choose parts of the document to convert into slides. That way, you can have more in the source document than what appears in the output document. There is no requirement that you consider all the content when converting. This is the key. At that point, the work is deciding how to architect the document to make it (a) semantic and (b) easy to pick apart. The more structured elements, the easier it's going to be.

Note that where the backend doesn't give you enough flexibility or context, you could add an extension such as a tree processor to reorganize the AST a bit before feeding the result into the backend. However, we should be careful to make the transformation logical so that you can conceptualize what is going to happen when looking at the source document. It doesn't hurt to be a bit more explicit with the roles in the source document to communicate what ends up where and the purpose it serves.

I'm starting to experiment with this myself (probably beginning in April / May). Instinct tells me that making the attempt is what is going to raise the concrete questions about the document architecture. I will definitely post findings as I go along.

Cheers,

-Dan

On Wed, Apr 1, 2015 at 9:22 AM, gernotstarke [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I want it all :-)
For software-archtitecture documentation I'd like to generate both html5 AND slide output...
(slides containing less content than html5, of course)

Any experience or ideas how to achieve that?

example of such content:
https://github.com/aim42/htmlsanitycheck, documentation subproject


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/how-to-setup-documents-for-BOTH-texthtml5-and-slide-reveal-js-output-tp2906.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



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

Re: how to setup documents for BOTH texthtml5) and slide (reveal.js) output?

LightGuardjp
I have a github repo started for a talking point and a place to place code: https://github.com/LightGuard/asciidoc_slides_conversation please use the repo so others in the community that may not be watching the list can also communicate.

On Wed, Apr 1, 2015 at 12:48 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Gernot,

This is something that Jason Porter has been contemplating a lot recently. He started a similar thread a while back (still ongoing).


What I would recommend is to modify the deck.js or reveal.js backends from https://github.com/asciidoctor/asciidoctor-backends so that they pick and choose parts of the document to convert into slides. That way, you can have more in the source document than what appears in the output document. There is no requirement that you consider all the content when converting. This is the key. At that point, the work is deciding how to architect the document to make it (a) semantic and (b) easy to pick apart. The more structured elements, the easier it's going to be.

Note that where the backend doesn't give you enough flexibility or context, you could add an extension such as a tree processor to reorganize the AST a bit before feeding the result into the backend. However, we should be careful to make the transformation logical so that you can conceptualize what is going to happen when looking at the source document. It doesn't hurt to be a bit more explicit with the roles in the source document to communicate what ends up where and the purpose it serves.

I'm starting to experiment with this myself (probably beginning in April / May). Instinct tells me that making the attempt is what is going to raise the concrete questions about the document architecture. I will definitely post findings as I go along.

Cheers,

-Dan

On Wed, Apr 1, 2015 at 9:22 AM, gernotstarke [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I want it all :-)
For software-archtitecture documentation I'd like to generate both html5 AND slide output...
(slides containing less content than html5, of course)

Any experience or ideas how to achieve that?

example of such content:
https://github.com/aim42/htmlsanitycheck, documentation subproject


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/how-to-setup-documents-for-BOTH-texthtml5-and-slide-reveal-js-output-tp2906.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/how-to-setup-documents-for-BOTH-texthtml5-and-slide-reveal-js-output-tp2906p2921.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--