search

Sigil-Ebook / Sigil

Sigil is a multi-platform EPUB ebook editor
GNU General Public License v3.0
5.92k stars 576 forks source link

User guide is outdated #119

Closed scj643 closed 6 years ago

scj643 commented 9 years ago

The userguide ePub is outdated and still points to the Google Code site.

dougmassay commented 9 years ago

The homepage link is the least of the things that need updated in that document (which as you can see hasn't been updated since v0.7.xx) ;)

Still ... you're right ... it does need some attention.

jaack65 commented 8 years ago

The documentation I could find for Sigil is for 0.7.2. The Help tab points F1 to a doc page that is blank! The GitHub Staff says: check the project's README file for an official website or contact information use the GitHub project's issue tracker contact the project's mailing list, if it has one contact the project owner directly by checking their GitHub profile for contact details For first time users of Sigil with a 2 yrar old user guide leaves a lot on the programming floor un documented for a new user. Do I even need Sigil if it is so neglected?

kevinhendricks commented 8 years ago

The bulk of the users guide is still relevant and still useful and many of the newer features are related to plugins. The plugin guide has been updated and help is always available on our user forums on Mobileread.

Our developer team is a tiny - just 2 people. Sigil is totally free as the developers volunteer their free time and skills and do not accept donations.

Since it does not require a developers skill to update the users guide. We have repeatedly requested help from non-programmer volunteers to update the guide but have received nothing but vague replies.

So instead of complaining, here is your chance to help out. Use Sigil to edit the users guide and help give back to the project.

bershan2 commented 7 years ago

I'd like to help out with the docs and translation.

I'm new to Sigil but love it, and would like to learn it much more. Therefore, I'd like to combine two good things: learning it and update the manual. Also, my end goal is to make it useful for someone else, so I need to translate it to Russian or, better, Ukrainian (I natively speak both).

Documentation: As far as I know, the most recent "Sigil User Guide" is the one discussed above and avaliable at https://github.com/Sigil-Ebook/Sigil/blob/master/docs/Sigil_User_Guide_0_7_2.epub. I'll start working on it now. Do you have recommendations where to start? If no, I'll just start moving from cover to cover.

Translation: I requested to be added into the editors group on transifex.com, my name is (spoiler alert) bershan2. I can't do anything until you accept the request.

Questions:

  1. Should I keep headers 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

    or use modern <!DOCTYPE html>

(Ir)relevant questions:

  1. Why does Sigil insist on including encoding="UTF-8", isn't it default? Or is it done just in case some "upstream" text in spine will be added/changed to non-UTF-8?
  2. I'm a little surprised to see that it is licensed under CC BY-SA 3.0, when Sigil is under GNU GPL 3. I'm not really familiar with either, but isn't GPL "copy left" license for software (ideal here as it is a software supplement), and CC is for creative work (manuals are not exactly creative)?
kevinhendricks commented 7 years ago

Please note, the Users Manual has already been significantly updated to match current Sigil and is waiting for proofing and editing. To see the latest version, visit our Sigil support forum on http://www.mobileread.com/forums and look for the Sigil forum.

There you will find a few threads on updating the user's manual and a link to the updated manual. Once the new manual has been edited and proofed, it will be committed to master here.

Translations of both Sigil and the manuals are always welcome. The leader of the transifex Russian and Ukrainian translations teams should be approving you as both translation teams were active at one time (not sure of their status now). If you make yourself known but hear nothing from them, I will then approve you for transifex.

GPL 2 and 3 are software licenses first and foremost. They do not fit well with non-software items such as User Guides, Books, and etc.

Kevin

On Jan 13, 2017, at 2:50 AM, bershan2 notifications@github.com wrote:

I'd like to help out with the docs and translation.

I'm new to Sigil but love it, and would like to learn it much more. Therefore, I'd like to combine two good things: learning it and update the manual. Also, my end goal is to make it useful for someone else, so I need to translate it to Russian or, better, Ukrainian (I natively speak both).

Documentation: As far as I know, the most recent "Sigil User Guide" is the one discussed above and avaliable at https://github.com/Sigil-Ebook/Sigil/blob/master/docs/Sigil_User_Guide_0_7_2.epub. I'll start working on it now. Do you have recommendations where to start? If no, I'll just start moving from cover to cover.

Translation: I requested to be added into the editors group on transifex.com, my name is (spoiler alert) bershan2. I can't do anything until you accept the request.

(Ir)relevant questions:

Why does Sigil insist on including encoding="UTF-8", isn't it default? Or is it done just in case some "upstream" text in spine will be added/changed to non-UTF-8? I'm a little surprised to see that it is licensed under CC BY-SA 3.0, when Sigil is under GNU GPL 3. I'm not really familiar with either, but isn't GPL "copy left" license for software (ideal here as it is a software supplement), and CC is for creative work (manuals are not exactly creative)? — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

kevinhendricks commented 7 years ago

Per your question ... you are editing an epub in epub2 format not pure html and as such the headers are correct as is. Once complete, we have plugins that will convert the user's manual (book) to epub3 so that both epub2 and epub3 versions are available.

bershan2 commented 7 years ago

Ok, I'll stick to epub2 for now. I asked because EPUB 3.1 has undated references to HTML http://www.idpf.org/epub/31/spec/epub-changes.html#sec-cdoc-undated . I noticed that Sigil does not support EPUB 3 fully... do you have docs for the pieces of code responsible for that? how can I improve EPUB 3.0/3.0.1 support and add 3.1 support. Note that 3.1 mostly cleans up things a bit: removes/deprecates some tags. It merely adds support for two font formats (WOFF 2.0 and SFNT) and remote resources. Should be really easy to add support for once EPUB 3.0 is fully supported.

kevinhendricks commented 7 years ago

A few things ...

We can use polyfils and Qt's new Chrome based WebEngine (Webkit replacement) to help but it will take some work to switchover from QtWebkit to Qt WebEngine's asynchronous callback approach for loading, javascript evaluation, etc, etc inside Sigil.

So if you are looking for a meaty project, porting both Preview and BookView in Sigil to use QtWebEngine would be a good start.

On Jan 13, 2017, at 2:53 PM, bershan2 notifications@github.com wrote:

Ok, I'll stick to epub2 for now. I asked because EPUB 3.1 has undated references to HTML http://www.idpf.org/epub/31/spec/epub-changes.html#sec-cdoc-undated . I noticed that Sigil does not support EPUB 3 fully... do you have docs for the pieces of code responsible for that? how can I improve EPUB 3.0/3.0.1 support and add 3.1 support. Note that 3.1 mostly cleans up things a bit: removes/deprecates some tags. It merely adds support for two font formats (WOFF 2.0 and SFNT) and remote resources. Should be really easy to add support for once EPUB 3.0 is fully supported.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

kevinhendricks commented 6 years ago

User's guide has been updated. Closing this issue as fixed