Have you Read The Fine Manual?

[Valloric]

The new manual is up on the site. Blog post with details here.
If you find any bugs, typos or have any suggestions, feel free to send them my way. You can post to this thread or open issues on the tracker.
I'll make this thread a sticky in a few days.
EDIT: The manual used to be a PDF, but is now a hosted set of web pages.

[zelda_pinwheel]

a manual ? great news ! that will be a huge help for beginners. thanks valloric ! i can't wait to take a look.

[kovidgoyal]

You can get sphinx to output epub now, just take the epub output plugin from the calibre source code. And drop the sphinx generated PDF, please.

[Valloric]

Originally Posted by kovidgoyal

You can get sphinx to output epub now, just take the epub output plugin from the calibre source code. And drop the sphinx generated PDF, please.

I know I can get it to output EPUB now, I can just use Sphinx from trunk. But the point is that I want a good looking PDF, and an epub version would be "icing on the cake".

But since Sphinx can't produce a PDF I'm satisfied with, I've decided to rewrite it in hand-coded LaTeX. So the plans for an epub version are out.

It's all in the blog post.

[kovidgoyal]

Why do you want a PDF? In you blog post you say you cant do complex layouts? what complex layouts can you not do with EPUB? ANd the last time I checked, the epub plugin in the sphinx tree was broken, badly.

[Valloric]

Originally Posted by kovidgoyal

Why do you want a PDF? In you blog post you say you cant do complex layouts? what complex layouts can you not do with EPUB?

There are many complex layouts you can do in epub, but you can't do everything. Off the top of my head, double columns. Not something I'd do in the manual (then again, maybe), but it's an option when you're working with LaTeX. Then there's floating sidebars: you can do those with epub, but I've yet to see it done in a way that wasn't ugly.

Then there's code listings: have you looked at code listings on small screens? Did it look nice? It will either wrap like crazy or you have to adjust the code directly, and that again doesn't look right.

Then there's RST itself. I dislike it. And Sphinx won't autonumber my figures, it doesn't let me change headers on a per chapter basis and lots and lots of other annoyances I've found over the last few weeks.

Bottom line, I didn't enjoy working with RST and Sphinx. It took away a lot of my layouting power, gave me grief and in the end, I don't like the result.

I could write an epub version directly, but I don't want to. It wouldn't look as good as I'd want it to, and it would prevent me from using all the various typesetting tricks I know. I strongly believe that technical manuals (at least the one I'm going to write) need to be read in large page format as a PDF.

I am not saying you can't use any kind of complex layouts with epub, just some of those layouts. And some of those are something I'd like to use.

"When all you use is a hammer, every problem looks like a nail." Sometimes (but rarely), a PDF is the right choice.

[kovidgoyal]

Hmm not good coming from the author of a program to edit a reflowable format.
Let's see if we can address some of your concerns:

1) Multi-col: The whole point of multicolumn layouts is that humans find it hard to read long lines. With a reflowable format you dont have long lines in the first place.

2) Floating sidebars:

Again the whole point of floating sidebars is to use the wide margin spaces available in fixed size layouts for large pages. There's no real functional difference between a floating sidebar and a centered block one. You're just used to seeing floating sidebars so you think asides must always be in the form of floating sidebars. Except perhaps that block ones interrupt reading flow a bit.

3) Code listings

You can put your code listing into a whitespace: pre element in which case it wont wrap and will look just as good as a PDF on small screen (better since you will be able to change the font size).

As for your dislike of reST, that's between you and reST

[zelda_pinwheel]

god knows i spend a lot of time defending epub until i'm blue in the face but i think valloric's position is reasonable here and he makes valid points. to address just one :

wrapping code in pre elements is not a great solution because if i read this on a small screen it means either i zoom and potentially half the code is cut off or i display it small enough so the entire line fits on the screen and the text is too small for me to read.

yes, i love epub for everything it can do, and for novels i can't imagine any reason not to use it, ever. but i also know there are a few specific cases in which pdf is just better, and valloric makes a good case for manuals being one of them.

the hammer / nail analogy seems pretty apt to me.

[Valloric]

Originally Posted by kovidgoyal

1) Multi-col: The whole point of multicolumn layouts is that humans find it hard to read long lines. With a reflowable format you dont have long lines in the first place.

That's not the only reason Kovid. There are aesthetic ones as well.

Originally Posted by kovidgoyal

2) Floating sidebars:

Again the whole point of floating sidebars is to use the wide margin spaces available in fixed size layouts for large pages. There's no real functional difference between a floating sidebar and a centered block one. You're just used to seeing floating sidebars so you think asides must always be in the form of floating sidebars. Except perhaps that block ones interrupt reading flow a bit.

I've bolded the relevant bit.

Originally Posted by kovidgoyal

3) Code listings

You can put your code listing into a whitespace: pre element in which case it wont wrap and will look just as good as a PDF on small screen (better since you will be able to change the font size).

Yes, in that case it will flow of the edge of the screen. That's far, far worse.

Originally Posted by kovidgoyal

Hmm not good coming from the author of a program to edit a reflowable format.

I've saved this one for last... gotta love politics.

Comments like these are precisely the reason why I went with RST + Sphinx in the first place and not just straight LaTeX. Sphinx offered the possibility of having a nice PDF along with a nice epub. It failed in that, at least for me.

You remind me of the PDF zealots. You know, the people who say that epub is useless and that everything should be typeset by hand and provided as PDF? You're just doing the reverse.

As it often in life turns out, reality is somewhere between the two extremes. And I'm glad you pointed out that I develop an epub editor. I also typeset about a hundred epub books a year and maybe three PDF ones.

But you're right, people now probably have good reasons to feel concerned about my "loyalties".

[kovidgoyal]

Originally Posted by Valloric

That's not the only reason Kovid. There are aesthetic ones as well.

Yes, but the aesthetic ones are only relevant if the reading area is large. Or are you saying that multiple columns of one word length look good?

I've bolded the relevant bit.

I agree it's not ideal, but is it really that bad?

Yes, in that case it will flow of the edge of the screen. That's far, far worse.

As opposed to PDF? Or are you saying that you want your users to read your manual only on large screens? In which case, I say, that code samples are not the most important thing in your manual and sacrificing reader flexibility for them, is the wrong trade-off.

You remind me of the PDF zealots. You know, the people who say that epub is useless and that everything should be typeset by hand and provided as PDF? You're just doing the reverse.

No I'm saying that I see no reason why a technical manual cannot be produced in EPUB. And I'm not a EPUB zealot, I am however a reflowable format zealot. I think that any document that claims to disseminate information in the form of language should not restrict the the ability of the user to consume/manipulate that information as flexibly as possible.

In other words, you are not presenting a coherent case for why you can't make the manual in EPUB. The sense I get is that you tried sphinx, didn't like its methodology/output and so decided to give up on producing a reflowable manual.

[Valloric]

Originally Posted by kovidgoyal

Or are you saying that you want your users to read your manual only on large screens?

Basically, yes.

Originally Posted by kovidgoyal

In which case, I say, that code samples are not the most important thing in your manual and sacrificing reader flexibility for them, is the wrong trade-off.

There aren't that important now, but who knows what the manual will contain six months from now.

And even if I had just one code listing, having it as an unreadable and ugly mess is just not acceptable.

Originally Posted by kovidgoyal

No I'm saying that I see no reason why a technical manual cannot be produced in EPUB.

I'm saying the same thing. I could produce this manual in epub format, but I'd be sacrificing a lot of what I wanted to achieve. There are other manuals out there that wouldn't have to sacrifice anything.

Originally Posted by kovidgoyal

And I'm not a EPUB zealot, I am however a reflowable format zealot.

That's the point I was trying to make. The reflowable vs. fixed war which I think is borderline retarded. Both have their pros and cons, and accordingly both have their uses.

The world is not black and white.

Originally Posted by kovidgoyal

The sense I get is that you tried sphinx, didn't like its methodology/output and so decided to give up on producing a reflowable manual.

You got the wrong sense. Have I mentioned I make about a hundred epubs a year, all in "direct" HTML + CSS without the use of Sphinx?

Originally Posted by kovidgoyal

In other words, you are not presenting a coherent case for why you can't make the manual in EPUB.

I'm tired of this argument and I won't try to convince you anymore.

[kovidgoyal]

Sigh, whatever.

[Valloric]

The manual is now a hosted set of web pages. Blog post here.

Even Kovid should be happy now...

[kovidgoyal]

You bet. Seriously if I have an HTML version of technical documentation available, I *never* read the PDF.

Since you are using sphinx, might I suggest a few tips? Like adding a sidebar to aid navigation, see http://calibre-ebook.com/user_manual/

[Valloric]

Originally Posted by kovidgoyal

Since you are using sphinx, might I suggest a few tips? Like adding a sidebar to aid navigation, see http://calibre-ebook.com/user_manual/

But there is a sidebar with a TOC.

It's on the right. It's just that it's not shown when you're looking at the contents page since that already is a TOC. But when you go to, say, the Epub Overview, you can see the sidebar TOC.