Quantcast

Help in approach on making a maintainable document

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
|  
Report Content as Inappropriate

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
Loading...