Login  Register

Flexibility of PDF Output and Hyphenation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Flexibility of PDF Output and Hyphenation

Beeblebrox
Hello,

as a LaTeX user for over 20 years now (on and off) I started using asciidoc(tor) a week ago, and I like the idea of less distraction at writing. Actually I did not write much yet, though, because I've distracted myself by collecting lots of information from the web about asciidoc(tor)'s toolchain - leaving me still confused.

Currently I'm trying AsciidocFX on Windows (which seems to include Asciidoctor) and the first thing I'm noticing is how little control I have over PDF output. It seems I'd have to create my own CSS stylesheet to get my desired style - which would be a major distraction from writing to me. The number of existing styles seems to be very small and they are rather IT biased. And even if I were CSS proficient I'd probably lack talent in design, so my style would probably be ugly :) Generally, the deeper I get into asciidoc-writing, the more it seems almost as complicated as using LaTeX.

What I could not find any information about is how to get hyphenation (in German) to work. An unhyphenated PDF would be an absolute no-go for me.

Another - less important - question: Is there a way to influence the style of the index or the bibliography like in LaTeX?

Thanks for listening,

B.
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

mojavelinux
Administrator
Welcome to Asciidoctor and thanks for the feedback.

You're correct that AsciidocFX is a editor / frontend for Asciidoctor. While we're excited about it's growth, you'll always get the best publishing experience using the Asciidoctor tools directly (esp as they continue to evolve themselves). That's true of any abstraction you introduce.

The official tool in Asciidoctor for converting to PDF is Asciidoctor PDF. Custom themes in Asciidoctor PDF are not developed in CSS, but rather a YAML-based configuration format that we developed. See the Asciidoctor Theming Guide (https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc) for details.

It's not a goal of Asciidoctor PDF to provide advanced layout capabilities, at least not right now. The goal is to give publishers enough control to apply a unique branding to the document. Based on the research we've conducted, this is what most people want.

If you need advanced layout capabilities when writing in AsciiDoc, you should continue to leverage the LaTeX toolchain for publishing by converting AsciiDoc to LaTeX. You can do so using the LaTeX converter, available at https://github.com/asciidoctor/asciidoctor-latex.

> the deeper I get into asciidoc-writing, the more it seems almost as complicated as using LaTeX. 

I think you're confusing writing with publishing. I think it's safe to say most agree that writing in AsciiDoc is simpler than LaTeX. I'd be interested to see a side-by-side comparison that illustrates LaTeX as the simpler format.

Publishing is always difficult, no matter what format you write in. The Asciidoctor toolchain tries to ease this path by avoiding complicated or obtuse tools (like XSLT) and providing sane defaults, but it still requires talent to produce something that's both unique and professional. Over time, more templates will emerge that provide off-the-shelf solutions, but that comes at a trade-off of lacking uniqueness.

> What I could not find any information about is how to get hyphenation (in German) to work. An unhyphenated PDF would be an absolute no-go for me.

That's currently not implemented in Asciidoctor PDF, but it's both possible and planned. See https://github.com/asciidoctor/asciidoctor-pdf/issues/20. If you need it sooner, and don't want to get into writing an extension, you can use the DocBook or LaTeX toolchains, which both support this feature. I recognize using these toolchains adds unnecessary complexity, which is why we're aiming for first-class support for hyphenation in Asciidoctor.

> Is there a way to influence the style of the index or the bibliography like in LaTeX?

In Asciidoctor PDF, not currently. If you want this feature and can describe the requirements, feel free to open an issue at https://github.com/asciidoctor/asciidoctor-pdf/issues.

To reiterate what I said above, you can always just convert to LaTeX and use the LaTeX toolchain. That's the flexibility AsciiDoc affords you.

Cheers,

-Dan



On Sat, Feb 25, 2017 at 9:56 AM, Beeblebrox [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello,

as a LaTeX user for over 20 years now (on and off) I started using asciidoc(tor) a week ago, and I like the idea of less distraction at writing. Actually I did not write much yet, though, because I've distracted myself by collecting lots of information from the web about asciidoc(tor)'s toolchain - leaving me still confused.

Currently I'm trying AsciidocFX on Windows (which seems to include Asciidoctor) and the first thing I'm noticing is how little control I have over PDF output. It seems I'd have to create my own CSS stylesheet to get my desired style - which would be a major distraction from writing to me. The number of existing styles seems to be very small and they are rather IT biased. And even if I were CSS proficient I'd probably lack talent in design, so my style would probably be ugly :) Generally, the deeper I get into asciidoc-writing, the more it seems almost as complicated as using LaTeX.

What I could not find any information about is how to get hyphenation (in German) to work. An unhyphenated PDF would be an absolute no-go for me.

Another - less important - question: Is there a way to influence the style of the index or the bibliography like in LaTeX?

Thanks for listening,

B.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Flexibility-of-PDF-Output-and-Hyphenation-tp5303.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



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

Re: Flexibility of PDF Output and Hyphenation

Beeblebrox
Thank you very much, Dan, for your detailed answer which reduced my confusion a lot.

Yes, you are right, I confused writing and publishing. And yes, writing in LaTeX is certainly more complicated than in Asciidoc.

The reason why I will continue with Asciidoc is that it seems to make collaborative work easier. It's really cool that Asciidoc is being rendered by GitHub meanwhile.

Also I can see the tremendous time and effort you are putting into this project paired with your impeccable communication skills. Asciidoctor seems very "alive" to me and thus worth supporting. Keep up the great work!

-Bjoern
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

Carsten
In reply to this post by mojavelinux
Hi Dan,

also from me thanks for your reply, it helped me a lot, too!

mojavelinux wrote
To reiterate what I said above, you can always just convert to LaTeX and
use the LaTeX toolchain. That's the flexibility AsciiDoc affords you.
Could you please elaborate on this?
When I use asciidoctor-latex, how can the generated LaTeX code be customized?

Best regards,
Carsten
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

shahryareiv
In reply to this post by Beeblebrox
If I may put my two cents in, I think that asciidoctor-latex is still not mature enough to support more than simple publishing needs. Actually, I think it does not even claim more. I tried it with academic documents and things are usually more complicated than its features. There are many content types and many options in rendering those types. At the same time asciidoctor-latex introduces " extended syntax " that I am not sure if I want to break compatibility of my asciidoc documents with that (except they get (? got) included in the asciidoc format).

I also consider asciidoctor-pdf rendering and its associated styling mechanism something as "good-enough" for simple publishing, but the level of customization is not what you want to publish, let's say a book, with. So, the other  viable choice is Asciidoc >>(asciidoctor)>> DocBook >>(dblatex + your customization)>> Latex >>(xe/pdflatex + your latex library )>> PDF .

IMHO, the important thing in this chain or any other chain is that the fundamental strength of asciidoc, that is user defined roles (and/or costume styles + modules) should be transferred downstream and the above chain could do most of this, although no so neat and easy. Why we need that? because of the very specific publishing needs you may need. For example, I need to have a very specially styled part for my "summary points" section. How can I define that? there is no internal style in asciidoc for that but I just need to to add ".summary" to the head of a block and I will see in Docbook that "<simpara role="summary"> ..." or in HTML "<p class="summary"> and then I can take care of how to typeset and style that specific content.

In the above mentioned chain, everything is asciidoc (including the roles, ids) is converted to docbook very clean and clearly (that has been the basic purpose of asciidoc, as far as I know). DBlatex is quite a mature convertor from docbook to latex but it is based on xslt and python and its maintenance does not seem to be very active (I have a feeling that the support might end some years ahead). The things in dblatex are somehow complicated and XSL things are not my favorite way of doing things. But anyway if you find that dblatex does not have the specific convertor for your "summary" section then you can add lines of xslt to dblatex to have a special conversion for <simpara> with role="summary" to something that you want in Latex. Then of course you need to write your latex macro, something like : \mySummary{}. Please note that even without your custom code (in xslt and latex), still the chain does a plenty of conversions in a good enough way.

I have used the above chain to typeset something like this (http://bit.ly/1R1uy0r). Almost everything (even the colophon) was originated in Asciidoc. The exceptions was, of course the cover, the figures, and the tables. I was not happy with how the tables are being translated down the stream and I had not time to write my own xslt convertor. So I just used the hack that asciidoctor has to send direct latex code (for PDF route not the HTML one).

The amount of typesetting features developed in Tex family is huge and I think that it takes Asciidoc-pdf a very long way/energy/contribution to reach that maturity in publishing, except that asciidoctor-pdf finds a way to internalize the whole latex chain.

There is also one more chain and that is Asciidoc >>>> HTML >> something >> PDF. There are HTML to PDF convertors such as Prince ( I noticed it being common with some academic publishers but not sure how fine it works). I know that W3C CSS Paged specifications are growing (https://www.w3.org/TR/css3-page/) but I guess still we need time for that to catch up with Tex maturity and fineness.

Personally, I think that Asciidoc >>>> HTML >> something >> PDF is the future. Asciidoc to HTML conversion is perfect and includes all the semantics specified in the original document. No need to have two paths (HTML and Docbook). One can convert an asciidoc flavored HTML to PDF (or other formats) any time later.  There are so many tools to work with HTML. HTML to Latex should be easier than Docbook to Latex due to tool options or at least the same. Meanwhile, we can wait for HTML to PDF through CSS Paged to get mature, without missing other things.
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

shahryareiv
By the way, regarding Latex vs Asciidoc. I think  it is not exactly a right comparison. Asciidoc tries to be purely semantic (there are very few deviations such as specifying "width" for images) but Latex mixes semantics with zillions of typesetting and formative definitions. I tried many of methods for converting Latex to HTML and most of them fail some where (including the tex4ht model that works at dvi level) because of this simple fact that it is not possible to automatically understand what is the semantic specification any part of text (except for the common basic macros and evironments)

Also, in latex it is quite possible that you use a package specific environment or macro and just few years later your code does not compile because the package is not maintained any more. In Asciidoc, I know that even if Asciidoctor dies, still my document is human readable without the needed of looking at a Asciidoc manual. Also my document has replicated itself to Docbook, HTML and PDF, while in Latex it has replicated only to PDF.
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

thierrybo
In reply to this post by mojavelinux
mojavelinux wrote
You're correct that AsciidocFX is a editor / frontend for Asciidoctor.
While we're excited about it's growth, you'll always get the best
publishing experience using the Asciidoctor tools directly (esp as they
continue to evolve themselves). That's true of any abstraction you
introduce.

The official tool in Asciidoctor for converting to PDF is Asciidoctor PDF.
Hi, sorry to dig up an old post. I am currently  discovering/learning asciidoc, asciidoctor, asciidoctor-pdf and I wonder about your sentence on asciidoctor PDF being the official tool for converting pdf files.

I understand it is easier to use asciidoctor-pdf, but as far as I am concerned there is also the a2x tool in asciidoctor.  It does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. So once you installed dependencies (for Debian):
#apt install docbook-xsl asciidoc-dblatex fop xsltproc

It is as easy to type:

a2x -f pdf file.adoc

as

asciidoctor-pdf file.adoc

what interests me the most is which one will be the easier to customize PDF output. For now I don't know which way to choose, seeing the default different outputs:
basic-example_a2x.pdf
basic-example__ascidoctor-pdf.pdf
basic-example__asciidocFX.pdf
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

mojavelinux
Administrator
The equivalent to a2x for Asciidoctor is fopub.


Keep in mind that while it's more current than a2x, it's also community supported.

Best,

-Dan

On Tue, Apr 16, 2019 at 11:45 AM thierrybo [via Asciidoctor :: Discussion] <[hidden email]> wrote:
mojavelinux wrote
You're correct that AsciidocFX is a editor / frontend for Asciidoctor.
While we're excited about it's growth, you'll always get the best
publishing experience using the Asciidoctor tools directly (esp as they
continue to evolve themselves). That's true of any abstraction you
introduce.

The official tool in Asciidoctor for converting to PDF is Asciidoctor PDF.
Hi, sorry to dig up an old post. I am currently  discovering/learning asciidoc, asciidoctor, asciidoctor-pdf and I wonder about your sentence on asciidoctor PDF being the official tool for converting pdf files.

I understand it is easier to use asciidoctor-pdf, but as far as I am concerned there is also the a2x tool in asciidoctor.  It does all the grunt work associated with generating and sequencing the toolchain commands and managing intermediate and output files. So once you installed dependencies (for Debian):
#apt install docbook-xsl asciidoc-dblatex fop xsltproc

It is as easy to type:

a2x -f pdf file.adoc

as

asciidoctor-pdf file.adoc

what interests me the most is which one will be the easier to customize PDF output. For now I don't know which way to choose, seeing the default different outputs:
basic-example_a2x.pdf
basic-example__ascidoctor-pdf.pdf
basic-example__asciidocFX.pdf


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Flexibility-of-PDF-Output-and-Hyphenation-tp5303p6849.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


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

Re: Flexibility of PDF Output and Hyphenation

thierrybo
Ok, just tried it, nice, a fourth different output ...

but it is not a  complete  a2x equivalent for ease of use. The equivalent to:

a2x -f pdf file.adoc
seems to be (didn't tried to pipe):

asciidoctor -b docbook -d book  -a data-uri! file.adoc && ./fopub file.xml && rm -f file.xml

Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Flexibility of PDF Output and Hyphenation

mojavelinux
Administrator
The AsciiDoc toolchains give you many options for producing output. That's one of its value propositions. It's up to you to decide which one is best for you. I will provide recommendations, but they are just that, recommendations.

Cheers,

-Dan

On Tue, Apr 16, 2019 at 12:43 PM thierrybo [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Ok, just tried it, nice, a fourth different output ...

but it is not a  complete  a2x equivalent for ease of use. The equivalent to:

a2x -f pdf file.adoc
seems to be (didn't tried to pipe):

asciidoctor -b docbook -d book  -a data-uri! file.adoc && ./fopub file.xml && rm -f file.xml




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Flexibility-of-PDF-Output-and-Hyphenation-tp5303p6852.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


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