Am I missing something big about book production?

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

Am I missing something big about book production?

shai
Hi,
I have a feeling I'm missing a big piece of knowledge about the process of book production. I've been using asciidoc for a few years both in our website and developer guide. It works great for these cases.

However, I'm now in the process of publishing a new book. I'm trying to get it to a level of refinement I see from big publishers like O'Reilly, Manning etc. both of which use Asciidoc. But I can't seem to get styling/functionality even close to what these books have. I'm assuming they don't use asciidoctor-pdf as it doesn't support footnotes/image wrapping etc. So I went with the FOP backend which would also allow customizing the docbook output for features that aren't supported in asciidoc yet (e.g. inline callouts, image wrapping etc.).

But is that what they do? Or is there some other toolchain in the professional realm that I'm ignorant about?
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

Andrew Carver
I can't address your question from relevant professional experience. But one thing is certain: the main, crucial book  on DocBook customization is the one by Bob Stayton, DocBook XSL: The Complete Guide, 4th edition. That book is available in softcover, or online in HTML (http://www.sagehill.net/docbookxsl/index.html). Everyone using DocBook needs to read at least some of that book, if just for learning the ropes, and to have it handy as a reference. By doing so, you'll see that the flexibility and control you have over the styling/functionality is pretty extensive, even using only stylesheet-parameters to customize. (If you're comfortable modifying XSLT, then you have basically complete control.)

Of course, Norman Walsh's book on DocBook itself is pretty important to have. Most editions of it are accessible online, including through at least v. 4.5 (https://tdg.docbook.org/tdg/4.5/docbook.html). As you know probably, the latest version is 5.0.

Beyond those, I think you might find interesting a book I stumbled across recently, DocBook for Writers. It's by Peter Lavin, apparently a Canadian gent with 10+ years as a technical writer--mostly using DocBook. I'm only in chapter 2, but so far my impression is that it's well-done and quite helpful for learning the practical nuts and bolts:

https://softcoded.com/books.php

https://www.amazon.com/DocBook-Writers-Peter-Lavin-ebook/dp/B00SNUNBK0/

Hope that helps address your questions...? Please follow up if not.

Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
Thanks!

I've had the first edition of the O'Reilly book years ago and browsed a bit through the new one. I know XSLT but it's a serious pain to go through the maze of weird XSL:FO settings. Thanks for the Docbook For Writers suggestion, I looked through the table of contents briefly and it seems to be more focused on the docbook aspects and not as much on the print/typesetting aspects which is what I'm trying to understand. I honestly don't know anything about typesetting and just started reading about it when I saw how badly my manuscript looks next to a professionally typeset book.

E.g. I've wrecked my head against just removing the "Chapter" prefix that gets pushed into the chapter headings, I see it in the localization code but it's really hard to follow this through guesswork. So my question is really: do publishers do that or do they export to a specific tool for typesetting and do the final process there?

Is there some tool for typesetting?  Do they export to InDesign using some tool or something else?

E.g. in this book from Manning (who use asciidoc/asciidoctor) we have a few elements that I find really hard to replicate. See the chapter heading with the underline, overly and missing "Chapter" prefix.  Notice the block below which is highlighted as a special case too:



Also look at the position of the numbering next to the paragraph. The numbering is effectively in the margin gutter and not in the body of the text allowing the title to align with the paragraph which looks amazing! I've seen examples where quotation marks etc. are placed in that area to keep alignment properly and glyph spacing is increased in a sentence to make justified text look better (reduce the spaces between words for justify).

(I'll post this in the next reply as it won't let me attach two images to one post)

Manning also has images where text flows around the images and their source code listings have the callouts embedded into the code. I saw an RFE for that and that feature is supported in docbook using LineAnnotations.

This looks like something that's done by a human being with design sensibilities, I'm assuming that person has some visual tools that take the file after processing and work with that. But being ignorant in this field I have no idea and don't even know the keywords to type into Google. I've spent the past couple of weeks googling various typesetting and other such keywords to no avail. I went through Atlas docs and still feel I'm missing something big.
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
Here's the second image I wanted to attach:

Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

Andrew Carver
Great questions!! I'll wait alongside you for someone more knowledgeable than I to reply
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

Andrew Carver
P.S. While we're waiting, though, here's something else I stumbled across just lately, HTMLBook--which bears looking into, I'd think, since O'Reilly came up with it:

https://www.balisage.net/Proceedings/vol10/html/Kleinfeld01/BalisageVol10-Kleinfeld01.html
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

Andrew Carver
P.P.S. Interestingly, there's been quite a bit of discussion--starting 5 years ago--on the need for an Asciidoctor HTML5 backend "that maximizes semantic constructs"; this included Dan Allen's suggestion, in Nov. 2013, that "it makes the most sense to align with the HTMLBook specification since a lot of thinking and discussion went into it to accomplish this very goal":

https://github.com/asciidoctor/asciidoctor/issues/242
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
I considered using HTML and its print facilities but I'm not sure if that would produce the result I want especially with pagination and attention to details.

I did make some progress but I don't think publishers work this way because I couldn't find any evidence of that.

I opened the PDF file in Sketch which is an excellent commercial vector drawing tool. It's not great for print but I use it a lot (it's possible this is better in Adobe illustrator).

Anyway, it opens the PDF and you can just edit the text and reposition it just like you can in any Sketch drawing. It arranges the 440 pages as individual images you can go through one by one and "fix" the layout of each and everyone of them.

I doubt Sketch is used by production teams since there is no CMYK support there but I think it would be good enough for me since the printing will be black and white anyway (covers are produced separately). Because this is literally a drawing app I can position everything I want where I want it and it will look crisp because it's a vector drawing app. I hope I won't spend a week on this only to discover a huge pitfall but I think I found the answer. The one  problem I have now is rendering the document without the callouts so I can embed them manually into the code...
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
I made a small trial to see if this approach is workable and I think it is...
The main pain point is that Sketch moves some of the text ever so slightly so I literally need to go over every page and realign text specifically syntax highlighted code.

Another pain point is the fact that I can't change pages so if changes I make need more or less space in the page I need to somehow deal with the whitespace. Those are solvable as the difference in look is staggering and worth the effort.

I did this with asciidoctor-pdf and sketch then exported the PDF.  It increased from 34mb to 54mb but worth it:

Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
For reference, this is the same code listing "before". Obviously things like titles etc. are super easy with Sketch:

Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
FYI I tried to do the same thing with Adobe Illustrator assuming that PDF editing would work better with Adobe. Unfortunately it didn't detect the fonts correctly and failed to resolve them. It then formatted the document incorrectly to boot.

I personally prefer Sketch so I'm fine with it. It's WAY better IMHO and cheaper. The one drawback is the lack of CMYK support but I think I can use Ghostscript for the conversion if I want to. I will probably go with a black and white book anyway which means CMYK doesn't really matter.

I'd still like to know what tools are used by professional publishing to do this as I doubt they use this approach...
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

markb
In reply to this post by shai
Take a look at PrinceXML. It's proprietary and a expensive, but does a great job at supporting print CSS rules that browsers don't yet support. I create online help systems with Asciidoctor and then convert my HTML source to book user guides with PrinceXML. You can get quite beautiful output. I use conditional rules in my .adoc files for content specific to print and screen that I switch on and off from the config file. I use a print-only CSS file that overrides screen styles for a print layout and adds pagination, headers/footers, etc for the printed book. There's nothing I haven't been able to accomplish with it yet, but there is a learning curve.
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
Thanks!

I ran into it when looking into the various options and mostly skimmed it as the path of HTML to PDF seems a bit painful to me. I'm also looking at things that might not be easily expressed via styling. E.g. a sentence that gets pushed to the next page...

I've already made huge progress on the book using the approach I outlined with Sketch. The starting point was the almost default output of asciidoctor-pdf. All the other design elements are drawn in Sketch see these:

https://www.codenameone.com/files/uber-book/create-an-uberclone-in-7-days-Chapter-1-preview.pdf

https://www.codenameone.com/files/uber-book/create-an-uberclone-in-7-days-Chapter-2-preview.pdf

Notice I used bleed to get chapter numbers and elements all the way to the edge of the page so you would be able to see the specific chapter by looking at the side of the book. Also notice that I replaced all the images with sketch diagrams since I used sketch to draw the diagrams to begin with. That means that all the graphics in the PDF is vector graphics and should be very crisp on print. I tried using the SVG approach but it had some issues...

A huge advantage here is the level of control, I can draw anything anywhere and adapt the diagram font/size with pixel perfect accuracy.

The downsides are:

- It's a LOT of work.

- Syntax highlighting doesn't format well into the PDF and gets jumbled in sketch so I need to move stuff around a lot

- Fonts don't match 100% so the code highlights e.g. `this is code` is shifted by one point down. This is true to one degree or other for every markup.

- I can't add/remove pages or even shift content too much as I don't want to break the index/ToC

- Links get broken, for me this isn't a big deal. I'll use the mobi/epub version for digital. This is only for print

I have ±430 pages and this is a pain to do. But I think I can push out something that will look as good (or even better) than a Manning book interior!

I'll try to write up an article about this process when I'm done and show some before/after images.
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

shai
My book is finally done!

I'm still waiting for proof copies so it isn't out yet. asciidoctor-epub3 worked really well for the digital version with only minor caveats so all seems good!

As promised I wrote an article for Hackernoon covering the process I went through to produce the print version with side by side screenshots and before/after PDFs for comparison. I left a lot of minor details out because it's really hard to explain details like dragging X here etc. If you have questions about the process I'd love to help.

Here's the article link: https://medium.com/@Codename_One/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410

Thanks!
Reply | Threaded
Open this post in threaded view
|

Re: Am I missing something big about book production?

mojavelinux
Administrator
Thanks for sharing!

First, the book looks absolutely great. Truly amazing.

The limits you've hit when styling with Asciidoctor PDF is where I hope that HTML + puppeteer + paged.js (paged media) will help. It should allow you to do what you're doing in Sketch, but using web technologies. I'll be posting more about it in the weeks to come.

Cheers,

-Dan

On Tue, Jul 24, 2018 at 2:41 AM shai [via Asciidoctor :: Discussion] <[hidden email]> wrote:
My book is finally done!

I'm still waiting for proof copies so it isn't out yet. asciidoctor-epub3 worked really well for the digital version with only minor caveats so all seems good!

As promised I wrote an article for Hackernoon covering the process I went through to produce the print version with side by side screenshots and before/after PDFs for comparison. I left a lot of minor details out because it's really hard to explain details like dragging X here etc. If you have questions about the process I'd love to help.

Here's the article link: https://medium.com/@Codename_One/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410

Thanks!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Am-I-missing-something-big-about-book-production-tp6365p6431.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
|

Re: Am I missing something big about book production?

wimdeblauwe
Where can I find those posts?