Register Guidelines E-Books Search Today's Posts Mark Forums Read

Go Back   MobileRead Forums > E-Book Software > Sigil

Notices

Reply
 
Thread Tools Search this Thread
Old 05-08-2010, 08:46 AM   #1
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
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.

Last edited by user_none; 09-29-2011 at 03:33 PM.
Valloric is offline   Reply With Quote
Old 05-08-2010, 08:48 AM   #2
zelda_pinwheel
zeldinha zippy zeldissima
zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.
 
zelda_pinwheel's Avatar
 
Posts: 27,828
Karma: 908606
Join Date: Dec 2007
Location: Paris, France
Device: eb1150 & is that a nook in her pocket, or she just happy to see you?
a manual ? great news ! that will be a huge help for beginners. thanks valloric ! i can't wait to take a look.
zelda_pinwheel is offline   Reply With Quote
 
Enthusiast
Old 05-08-2010, 09:04 AM   #3
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
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.
kovidgoyal is offline   Reply With Quote
Old 05-08-2010, 09:11 AM   #4
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
Quote:
Originally Posted by kovidgoyal View Post
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.
Valloric is offline   Reply With Quote
Old 05-08-2010, 09:12 AM   #5
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
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.
kovidgoyal is offline   Reply With Quote
Old 05-08-2010, 09:32 AM   #6
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
Quote:
Originally Posted by kovidgoyal View Post
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.

Last edited by Valloric; 05-08-2010 at 09:36 AM.
Valloric is offline   Reply With Quote
Old 05-08-2010, 09:45 AM   #7
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
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
kovidgoyal is offline   Reply With Quote
Old 05-08-2010, 09:49 AM   #8
zelda_pinwheel
zeldinha zippy zeldissima
zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.zelda_pinwheel ought to be getting tired of karma fortunes by now.
 
zelda_pinwheel's Avatar
 
Posts: 27,828
Karma: 908606
Join Date: Dec 2007
Location: Paris, France
Device: eb1150 & is that a nook in her pocket, or she just happy to see you?
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.
zelda_pinwheel is offline   Reply With Quote
Old 05-08-2010, 10:00 AM   #9
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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".


Last edited by Valloric; 05-08-2010 at 10:17 AM. Reason: typo
Valloric is offline   Reply With Quote
Old 05-08-2010, 10:28 AM   #10
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
Quote:
Originally Posted by Valloric View Post
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?

Quote:
I've bolded the relevant bit.
I agree it's not ideal, but is it really that bad?


Quote:
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.


Quote:
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.
kovidgoyal is offline   Reply With Quote
Old 05-08-2010, 10:42 AM   #11
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
Quote:
Originally Posted by kovidgoyal View Post
Or are you saying that you want your users to read your manual only on large screens?
Basically, yes.

Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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.

Quote:
Originally Posted by kovidgoyal View Post
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?

Quote:
Originally Posted by kovidgoyal View Post
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.
Valloric is offline   Reply With Quote
Old 05-08-2010, 11:04 AM   #12
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
Sigh, whatever.
kovidgoyal is offline   Reply With Quote
Old 05-09-2010, 10:34 AM   #13
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
The manual is now a hosted set of web pages. Blog post here.

Even Kovid should be happy now...

Last edited by Valloric; 05-09-2010 at 10:41 AM.
Valloric is offline   Reply With Quote
Old 05-09-2010, 11:09 AM   #14
kovidgoyal
creator of calibre
kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.kovidgoyal ought to be getting tired of karma fortunes by now.
 
kovidgoyal's Avatar
 
Posts: 25,913
Karma: 5035037
Join Date: Oct 2006
Location: Mumbai, India
Device: Various
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/
kovidgoyal is offline   Reply With Quote
Old 05-09-2010, 11:19 AM   #15
Valloric
Created Sigil, FlightCrew
Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.Valloric ought to be getting tired of karma fortunes by now.
 
Valloric's Avatar
 
Posts: 1,978
Karma: 350515
Join Date: Feb 2008
Device: Sony Reader PRS 505
Quote:
Originally Posted by kovidgoyal View Post
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.
Valloric is offline   Reply With Quote
Reply

Thread Tools Search this Thread
Search this Thread:

Advanced Search

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
Do you count Kindle manual towards books you've read? mrzerga Amazon Kindle 14 09-15-2010 06:13 AM
PRS-505 Fine Verticle Black Lines on Screen! benong Sony Reader 1 08-20-2010 11:14 AM
Classic Books transfer fine to device....but not to SD card krighton Barnes & Noble NOOK 8 07-02-2010 08:18 AM
Trying to read the manual p3aul Calibre 2 07-26-2009 10:50 PM
I'm sure he's fine. Taylor514ce Lounge 32 04-04-2009 04:34 AM


All times are GMT -4. The time now is 05:58 PM.


MobileRead.com is a privately owned, operated and funded community.