Indented paragraph

568 views
Skip to first unread message

sal migondis

unread,
Apr 16, 2011, 10:24:57 AM4/16/11
to asciidoc
I occasionally need to indent a paragraph, sometimes two or three.

I normally use the 'quote' block, but I was wondering whether there
were other options, such as using a specific tag or possibly a one
column table?

I see that this can also be done via custom stylesheets, but I'm not
sure where these should go and what output format they control (pdf,
html, xhtml).

Do I need to set up a ~/.asciidoc tree reproducing the structure of /
etc/asciidoc, and if so, will my custom definitions be merged with the
system-wide tree, or do I need to copy the entire tree and customize
the copy?

Thanks,

Sal

Lex Trotman

unread,
Apr 16, 2011, 10:50:18 PM4/16/11
to asci...@googlegroups.com

Hi Sal,

The "proper" way to do it is to use the role attribute to mark
paragraphs you want indented [role="indented"]. Your asciidoc source
is then backend independent.

For xhtml output from asciidoc it is easy, just have a file containing
the CSS fragment:

.indented { margin-left : 10em }

and start your asciidoc file with

:stylesheet: full_absolute_path_to_the_file_with_the _css_fragment

Because of the fundamental cascading feature of CSS you don't need to
change or copy any of the system files.

For HTML 4 this will not work with the current released version of
asciidoc, but a patch has been accepted to allow it, and should be in
the next release (or hg version if you are adventurous).

For docbook the method of defining how the role maps to layout is
defined by the docbook toolchain you use, and the method of specifying
it is also toolchain dependent so you will have to look up their
documentation.

Cheers
Lex

>
> --
> You received this message because you are subscribed to the Google Groups "asciidoc" group.
> To post to this group, send email to asci...@googlegroups.com.
> To unsubscribe from this group, send email to asciidoc+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
>
>

Stuart Rackham

unread,
Apr 16, 2011, 11:56:44 PM4/16/11
to asci...@googlegroups.com

From the User Guide:
``DocBook XSL Stylesheets translate DocBook role attributes to HTML class
attributes; CSS can then be used to style the generated HTML.''

See http://www.sagehill.net/docbookxsl/UsingCSS.html

Cheers, Stuart

Lex Trotman

unread,
Apr 17, 2011, 1:19:11 AM4/17/11
to asci...@googlegroups.com
[...]

> From the User Guide:
> ``DocBook XSL Stylesheets translate DocBook role attributes to HTML class
> attributes; CSS can then be used to style the generated HTML.''
>
> See http://www.sagehill.net/docbookxsl/UsingCSS.html
>
> Cheers, Stuart
>

Hi Stuart,

Ok, I give up, how do you specify *additional* css stylesheets to a2x
generated xhtml? The --stylesheet option *replaces* the whole
stylesheet it doesn't add extra.

And of course it doesn't apply to anything that goes through dblatex
or fop to generate output, you still need to use their particular
methods of mapping roles to layout.

Cheers
Lex

Stuart Rackham

unread,
Apr 17, 2011, 2:05:01 AM4/17/11
to asci...@googlegroups.com

On 17/04/11 17:19, Lex Trotman wrote:
> [...]
>> From the User Guide:
>> ``DocBook XSL Stylesheets translate DocBook role attributes to HTML class
>> attributes; CSS can then be used to style the generated HTML.''
>>
>> See http://www.sagehill.net/docbookxsl/UsingCSS.html
>>
>> Cheers, Stuart
>>
>
> Hi Stuart,
>
> Ok, I give up, how do you specify *additional* css stylesheets to a2x
> generated xhtml? The --stylesheet option *replaces* the whole
> stylesheet it doesn't add extra.

You are exactly right and it would be nice to be able to specify an additional
stylesheet instead of having to replace the existing docbook-xsl.css stylesheet.
The thing is that DocBook XSL Stylesheets mandates the single docbook-xsl.css
file (the DocBook XSL html.stylesheet parameter) so the only way to do it would
be to add a CSS @import rule to the distributed docbook-xsl.css file, but the
problem with this is that @import rules must appear before any other rules in
the stylesheet so it's only useful for importing the base CSS. So you're left
with having to import the distributed docbook-xsl.css from a your custom CSS
file and redefining the DocBook XSL html.stylesheet parameter e.g. file
mystyles.css:

@import(docbook-xsl.css)
/* put custom CSS here. */

Call a2x with this additional argument:

--xsltproc-opts "--stringparam html.stylesheet mystyles.css"

Finally, because the docbook-xsl.css is no longer directly referenced by the
generated HTML, you would need to explicitly specify it with an a2x --resource
argument.

I can't vouch for all this because I haven't tried it, but it might be a good
candidate for a FAQ.


>
> And of course it doesn't apply to anything that goes through dblatex
> or fop to generate output, you still need to use their particular
> methods of mapping roles to layout.

Yes this is much more difficult and it's way out of my comfort zone.

Cheers, Stuart


>
> Cheers
> Lex
>

Lex Trotman

unread,
Apr 17, 2011, 2:59:41 AM4/17/11
to asci...@googlegroups.com
[...]
>  @import(docbook-xsl.css)

Ok, a quick test works but the actual line is:

@import "docbook-xsl.css";

>  /* put custom CSS here. */
>
> Call a2x with this additional argument:
>
>  --xsltproc-opts "--stringparam html.stylesheet mystyles.css"
>
> Finally, because the docbook-xsl.css is no longer directly referenced by the
> generated HTML, you would need to explicitly specify it with an a2x
> --resource argument.

Correct.

>
> I can't vouch for all this because I haven't tried it, but it might be a
> good candidate for a FAQ.
>

Works as advertised with the corrected import syntax.

>
>>
>> And of course it doesn't apply to anything that goes through dblatex
>> or fop to generate output, you still need to use their particular
>> methods of mapping roles to layout.
>
> Yes this is much more difficult and it's way out of my comfort zone.
>

+1, thats why I use Asciidoc :-)

So to summarise advice to the OP:

For asciidoc generated HTML, easy peasy, as per previous post
For a2x generated HTML, possible but a bit more complicated.
For pdf or other docbook toolchain generated format, might be possible
but sorry, can't help you further, maybe someone else can.

Cheers
Lex

sal migondis

unread,
Apr 17, 2011, 8:10:46 AM4/17/11
to asciidoc
On Apr 17, 2:59 am, Lex Trotman <ele...@gmail.com> wrote:

[...]

> So to summarise advice to the OP:
>
> For asciidoc generated HTML, easy peasy, as per previous post
> For a2x generated HTML, possible but a bit more complicated.
> For pdf or other docbook toolchain generated format, might be possible
> but sorry, can't help you further, maybe someone else can.

Thanks much to both you and Stuart. I'm relieved to note that my
question made some sense after all.

I wrote a couple of bash functions that invoke a2x to generate one-
page
and chunked html, .pdf (via dblatex, I like the default look better)
and plain
ASCII, so that I can take a quick glance at these different output
formats
and check they are OK. I am more concerned about the output not being
a total mess than creating elegant fancy typesetting, something that
could
take years to learn properly and to me really only makes sense for
printed
documents.

So in fine, it looks like my initial hope of a magic bullet that 'just
works' in all
contexts, regardless of the toolchain and the ouput format is.. 'not
going to
happen'.

Not a major issue, since I only need to indent paragraphs on rare
occasions.

I think that rather than attempt to do this the right way via
stylesheets
specific to each format, I will experiment with the quick and dirty
approach
that I had in mind at one point, with a one-column table with no frame
and
see if I can get this to do roughly what I am after. Otherwise, I'll
take a
look at the style sheet solutions.

As to style sheets, thanks also for answering my other question..
whether
they replace or complement the system-wide style sheets. I understand
that this is not really asciidoc-specific, but it was a little unclear
from my
superficial reading of the asciidoc documentation.

I'm replying from a web browser, so hopefully my post will follow the
list's
guidelines.

Thanks,

Sal.

Lex Trotman

unread,
Apr 17, 2011, 8:29:35 AM4/17/11
to asci...@googlegroups.com
[...]

> I think that rather than attempt to do this the right way via
> stylesheets
> specific to each format, I will experiment with the quick and dirty
> approach
> that I had in mind at one point, with a one-column table with no frame
> and
> see if I can get this to do roughly what I am after. Otherwise, I'll
> take a
> look at the style sheet solutions.

Unfortunately tables are not the most portable feature either,
especially in relation to size and positioning, but maybe it will do
what you want.

Basically, docbook and therefore Asciidoc is content markup, not
layout markup, but you are trying to do layout. :-)

>
> As to style sheets,  thanks also for answering my other question..
> whether
> they replace or complement the system-wide style sheets. I understand
> that this is not really asciidoc-specific, but it was a little unclear
> from my
> superficial reading of the asciidoc documentation.

Remember that cascading stylesheets only apply to HTML/XHTML.

>
> I'm replying from a web browser, so hopefully my post will follow the
> list's
> guidelines.
>

Wrapped a little funny, but otherwise ok.

Cheers
Lex

sal migondis

unread,
Apr 17, 2011, 8:59:24 AM4/17/11
to asciidoc
On Apr 17, 8:29 am, Lex Trotman <ele...@gmail.com> wrote:

[...]

> Unfortunately tables are not the most portable feature either,
> especially in relation to size and positioning, but maybe it will do
> what you want.
>
> Basically, docbook and therefore Asciidoc is content markup, not
> layout markup, but you are trying to do layout. :-)

Thanks Lex, that's precisely what I meant by 'quick and dirty'.
And I am not too sure this is something I want to implement
as a matter of course. Bound to come back and bite me sooner
or later :-)

[..]

> Remember that cascading stylesheets only apply to HTML/XHTML.

Good point. Thanks for the reminder.

> > I'm replying from a web browser, so hopefully my post will follow
> > the list's guidelines.
>
> Wrapped a little funny, but otherwise ok.

Fooled yet again by the proportional font. Always looks like less
characters than there actually are.

Sal.

Lex Trotman

unread,
Apr 22, 2011, 12:46:01 AM4/22/11
to asci...@googlegroups.com
[...]

>> Ok, I give up, how do you specify *additional* css stylesheets to a2x
>> generated xhtml?  The --stylesheet option *replaces* the whole
>> stylesheet it doesn't add extra.
>
> You are exactly right and it would be nice to be able to specify an
> additional stylesheet instead of having to replace the existing
> docbook-xsl.css stylesheet. [...]

Eureka!! the docbook-xsl html.stylesheet parameter takes a space
separated list of css stylesheets and generates separate <link>
entities for them in order. So just specify
--stylesheet="docbook-xsl.css /home/lex/whatever.css".

Cheers
Lex

Stuart Rackham

unread,
Apr 22, 2011, 6:01:07 AM4/22/11
to asci...@googlegroups.com

That's a great tip, I'll make sure I add it to the FAQ
http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_render_indented_paragraphs

Cheers, Stuart


>
> Cheers
> Lex
>

Lex Trotman

unread,
Apr 22, 2011, 7:00:12 AM4/22/11
to asci...@googlegroups.com
>> Eureka!!  the docbook-xsl html.stylesheet parameter takes a space
>> separated list of css stylesheets and generates separate<link>
>> entities for them in order. So just specify
>> --stylesheet="docbook-xsl.css /home/lex/whatever.css".
>
> That's a great tip, I'll make sure I add it to the FAQ
> http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_render_indented_paragraphs
>
> Cheers, Stuart
>

Also the a2x man page --stylesheet option probably should say it also
takes a space separated list.

Cheers
Lex

PS the things you find when looking for something else :-)

Stuart Rackham

unread,
Apr 23, 2011, 12:12:24 AM4/23/11
to asci...@googlegroups.com

On 22/04/11 23:00, Lex Trotman wrote:
>>> Eureka!! the docbook-xsl html.stylesheet parameter takes a space
>>> separated list of css stylesheets and generates separate<link>
>>> entities for them in order. So just specify
>>> --stylesheet="docbook-xsl.css /home/lex/whatever.css".
>>
>> That's a great tip, I'll make sure I add it to the FAQ
>> http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_render_indented_paragraphs
>>
>> Cheers, Stuart
>>
>
> Also the a2x man page --stylesheet option probably should say it also
> takes a space separated list.

Done, see:
http://code.google.com/p/asciidoc/source/detail?r=59df1c5a0faaca9c8822622f09c187682896d490

Cheers, Stuart

Reply all
Reply to author
Forward
0 new messages