Help in approach on making a maintainable document

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

Help in approach on making a maintainable document

Linda
I'd like to ask for some help/advice on how to make a maintainable document set. I'll bring forward the current setup first, then what I'd like to have and looked into so far.

The document set has been converted from multiple Word documents to many more asciidoc files. I have taken plain text and added asciidoc syntax. The asciidoc is converted by Maven using asciidoctorj. There is html output as well as pdf. I have created a few 'main' asciidoc files, that include other files as their chapters. Bigger chapters have been chopped up in separate asciidoc files in the same manner.

The blocks I'd like to have different mark up for, are currently marked up as admonition/example blocks. They can contain tables:

[NAME]
====
abcdefg..
====

I'd like to have blocks of text with different mark up and different alignment on the page:
* With the help of the extension, I have made a custom admonition block. I also made the necessary changes for the pdf theme. This works.
* Other blocks I'd like to see without an icon, aside of the text, floating. I cannot see this working as admonition or example block. I tried Sidebar block (****) but didn't see a difference and asciidoc markup/tables were not created.
* And a few blocks I want to be within the margins of the body text, but with different mark up than the 'example block' they are identified as right now. I want to keep the current example blocks too.

Can someone please help/advice me how I can make changes in the styles? Preferable I'd like to have the style directions as much as possible in CSS/PDF theme and not at every block within the asciidoc files. If creating an extension gives a decent solution, I'm all in for that, but I have no experience with Ruby and could use some directions. :)
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

Linda
I might have asked for too much at once :) I'll break it up in smaller questions. If something is not possible, please let me know, so I can find a different way of presenting the data.

Is it possible to resize an example block so it wraps tightly around text? (like the '%autowidth' attribute for tables)

Thanks in advance for any help offered!
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

apnadkarni
In reply to this post by Linda
I'm something of a newbie myself, but have you looked at using roles for this with appropriate styling using CSS?

/Ashok
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

Linda
Hi Ashok,

Thank you for the suggestion. I looked briefly into roles, perhaps too brief. As it may help me with the html output, I am not so sure if I can use that for pdf as well. That kept me from digging into it.

Hoping that someone can enlighten me on that in the meantime, I'll give it a try!
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

mojavelinux
Administrator
In reply to this post by Linda
Hi Linda! There's been a flurry of activity lately, so I'm a bit behind on some of the threads. But I didn't forget about you!

On Tue, Mar 21, 2017 at 4:32 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Is it possible to resize an example block so it wraps tightly around text? (like the '%autowidth' attribute for tables)

There's no direct support for the width attribute on blocks (aside from tables), though I've often needed that feature as well. I opened an issue to track it. https://github.com/asciidoctor/asciidoctor/issues/2099

Ashok is right that one way to do this today is to use a role. The default Asciidoctor stylesheet already provides a left and right role to float the block to the left and right, respectively. But that will only work if the content is shorter than the width of the page. You'd need to add another role to constrain the width. Something like;

[.left.span-50]
====
Lorem ipsum dolor sit amet, minim quaestio argumentum ex nam, populo albucius lobortis nam ea. Et ius elit movet homero.
====

Then, in a docinfo file (or your own stylesheet) you'd define a style like:

.span-50 {
  width: 50%;
}

.left.span-50 {
  margin-right: 1.25em;
  margin-bottom: 0;
}

Another way to make this work is to put the example block inside a table with no frame or grid.

[.left,width=50%]
|===
a|
====
Lorem ipsum dolor sit amet, minim quaestio argumentum ex nam, populo albucius lobortis nam ea. Et ius elit movet homero.
====
|===

While that's not very semantic, it does work. You can also do the same in Asciidoctor PDF. However, Asciidoctor PDF cannot wrap text around blocks. That's an extremely complicated layout problem given the toolset that Prawn gives us and therefore can only be done on a case-by-case basis using custom code. You could still use a multi-column table to position blocks side-by-side, but you can't have the typical article-style wrapping behavior.

I hope that helps!

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

mojavelinux
Administrator
In reply to this post by Linda
It's important to keep in mind that Asciidoctor PDF is not really designed for advanced layouts. The idea is to allow you to apply a branding (fonts, shading, borders, etc) to the layout that we set. PDF is not really a "styleable" medium, so most of the layout has to be hard coded. Over time, the styling mechanism has gradually matured as we find ways to express the layout in configuration...but it's best to think of it as linear. If you are willing to dive into Ruby, you can override methods and change the layout that is used...but advanced layouts are still very hard to achieve using the library that we use (Prawn).

If you want the exact layout that you have in HTML in your PDF, then I recommend using an HTML to PDF export. I consider that to be a very different use case for a different audience. If that feels like the right approach for you, then I recommend that you take it. There's no one right way. Just what is right for you.

Cheers,

-Dan

On Tue, Mar 28, 2017 at 2:42 AM, Dan Allen <[hidden email]> wrote:
Hi Linda! There's been a flurry of activity lately, so I'm a bit behind on some of the threads. But I didn't forget about you!

On Tue, Mar 21, 2017 at 4:32 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Is it possible to resize an example block so it wraps tightly around text? (like the '%autowidth' attribute for tables)

There's no direct support for the width attribute on blocks (aside from tables), though I've often needed that feature as well. I opened an issue to track it. https://github.com/asciidoctor/asciidoctor/issues/2099

Ashok is right that one way to do this today is to use a role. The default Asciidoctor stylesheet already provides a left and right role to float the block to the left and right, respectively. But that will only work if the content is shorter than the width of the page. You'd need to add another role to constrain the width. Something like;

[.left.span-50]
====
Lorem ipsum dolor sit amet, minim quaestio argumentum ex nam, populo albucius lobortis nam ea. Et ius elit movet homero.
====

Then, in a docinfo file (or your own stylesheet) you'd define a style like:

.span-50 {
  width: 50%;
}

.left.span-50 {
  margin-right: 1.25em;
  margin-bottom: 0;
}

Another way to make this work is to put the example block inside a table with no frame or grid.

[.left,width=50%]
|===
a|
====
Lorem ipsum dolor sit amet, minim quaestio argumentum ex nam, populo albucius lobortis nam ea. Et ius elit movet homero.
====
|===

While that's not very semantic, it does work. You can also do the same in Asciidoctor PDF. However, Asciidoctor PDF cannot wrap text around blocks. That's an extremely complicated layout problem given the toolset that Prawn gives us and therefore can only be done on a case-by-case basis using custom code. You could still use a multi-column table to position blocks side-by-side, but you can't have the typical article-style wrapping behavior.

I hope that helps!

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

mojavelinux
Administrator
In reply to this post by Linda

On Tue, Mar 28, 2017 at 2:47 AM, Dan Allen <[hidden email]> wrote:
but advanced layouts are still very hard to achieve using the library that we use (Prawn).

Combined with the fact that the content can be pretty much any combination of blocks, which is really what makes it so tricky.


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

Linda
In reply to this post by mojavelinux
Hi Dan,

Thank you for your replies! I'll take it all in consideration in defining the styles/creating pdf files. It's going to depend a bit, but it may be that the html becomes more important than the pdf over time. If possible, I'll look into a solution whereby I can work from the css to print things nicely, to replace the pdf (it's not my decision to make). Also, not a hero on css, but then it's a direction I can dig into.

Guess what... I want to put a table inside the block to space out some images evenly ;D
I'll fiddle a bit more with the tables. Can you let text wrap around a table?
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

mojavelinux
Administrator

On Tue, Mar 28, 2017 at 3:16 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'll fiddle a bit more with the tables. Can you let text wrap around a table?

Yep. I explain how in this issue. https://github.com/asciidoctor/asciidoctor/issues/2099#issuecomment-289702351

(but, again, only for HTML).

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

apnadkarni
In reply to this post by Linda
If you get the HTML layout as you want it, you might want to try generating a PDF with wkhtmltopdf and see if that suffices for your purposes. I've only used that for simple documents though.

/Ashok
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

Linda
A little update...

I got some talks and got an 'ok' to focus mainly on creating the html. So for now, I'll leave the pdf output as it is.
Thank you Ashok for mentioning the tool :)
And I hope that asciidoc syntax will remain the same disregard the output, as much as possible, as that would be its strength :)

I hope to be able to spend some more time on the documents in the second part of next week. The I'll have more time to make the wrapping work.

I'll open up a new thread if necessary. Have a nice weekend!
Reply | Threaded
Open this post in threaded view
|

Re: Help in approach on making a maintainable document

mojavelinux
Administrator

On Fri, Mar 31, 2017 at 9:43 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
And I hope that asciidoc syntax will remain the same disregard the output, as much as possible, as that would be its strength :)

That is certainly the goal. Some formats, like PDF, just make that extremely difficult to achieve.

There's no question that the content world is converging on using HTML as the main rendering engine for content. I support that movement because it gives us one consistent way to arrange content. PDF is a big bump in that road that we still have to deal with until there's a reliable way to send a self-contained document. EPUB was supposed to be that but has failed miserably due to the fact that most readers don't full embrace the web.

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux