Plugin Development

[KevinH]

Hi Doitsu,
I am not sure I see the need to bundle this with Sigil for plugins. It could always be added and used with "Open With" inside Sigil itself if that is something a user might be interested in.

The plugin interface was designed to automate repetitive tasks that can not be easily done inside a gui based environment, not to extend Sigil's gui itself. So how exactly would this be useful for plugins? If possible, please provide examples of how plugins would need a full editor to perform its functions.

DiapDealer, what do you think?

[Doitsu]

Originally Posted by KevinH

I am not sure I see the need to bundle this with Sigil for plugins. It could always be added and used with "Open With" inside Sigil itself if that is something a user might be interested in.

Of course, users could select their favorite editor with "Open With," however, it'd be very difficult to bundle QScintilla with a plugin, because it's a PyQt5 plugin.

Originally Posted by KevinH

The plugin interface was designed to automate repetitive tasks that can not be easily done inside a gui based environment, not to extend Sigil's gui itself.

IMHO, features such as code folding and auto-completion would make some edits easier moreover the QScintilla API is very user-friendly and requires hardly any code. I cobbled together a simple QScintilla edit plugin, which uses the following code:

Spoiler:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
import sys, os
from PyQt5 import Qsci
from PyQt5.QtGui import QFont, QFontMetrics, QColor
from PyQt5.QtWidgets import QApplication, QMessageBox

def run(bk):
    
    #=====================
    # save changes
    #=====================
    def SaveChanges():
        new_html = editor.text()
        if new_html != html:
            answer = QMessageBox.question(editor, "Save changes?", "Do you want to save the changes.")
            if answer == QMessageBox.Yes:
                bk.writefile(html_id, new_html)
                print('{} was updated.'.format(file_name))
        else:
            print('{} was NOT updated.'.format(file_name))

    #===================================
    # select a file
    #===================================
    
    # get all selected files
    file_names = list(bk.selected_iter())
    if file_names != []:
        # only use the first file
        html_id = file_names[0][1]
        file_name = os.path.basename(bk.id_to_href(html_id))
        # only load HTML files
        if bk.id_to_mime(html_id) == 'application/xhtml+xml':
            html = bk.readfile(html_id)
        else:
            print('No HTML file selected.')
            return
    else:
        print('You must select an HTML file.')
        return
    
    
    #=====================================
    # define QScintilla window
    #=====================================
    app = QApplication(sys.argv)
    editor = Qsci.QsciScintilla()
    lexer = Qsci.QsciLexerHTML(editor)
    editor.setLexer(lexer)

    # define autocompletion parameters
    editor.setAutoCompletionThreshold(1)
    editor.setAutoCompletionSource(Qsci.QsciScintilla.AcsAll)

    # define font
    font = QFont()
    font.setFamily('Courier')
    font.setFixedPitch(True)
    font.setPointSize(10)
    
    # editor code page
    editor.setUtf8(True)
    
    # editor font
    editor.setFont(font)
    editor.setMarginsFont(font)
    fontmetrics = QFontMetrics(font)
    editor.setMarginsFont(font)
    
    # margins & line numbers
    editor.setMarginWidth(0, fontmetrics.width("00000") + 6)
    editor.setMarginLineNumbers(0, True)
    editor.setMarginsBackgroundColor(QColor("#cccccc"))
    editor.setMarginWidth(2, 15)
    
    # line wrapping
    editor.setWrapMode(editor.WrapWord)
    
    # enable folding
    editor.setFolding(True)

    # window size
    editor.setMinimumSize(600, 450)
    editor.show()
    editor.setText(html)
    
    # save changes
    app.aboutToQuit.connect(SaveChanges)
    
    # display editor
    app.exec_()
    
    print('Done')
    
    return 0

def main():
    print('I reached main when I should not have\n')
    return -1

if __name__ == "__main__":
    sys.exit(main())

(All the plugin does is load the HTML code of current file into the editor and when you close the editor it asks you whether you want to save the changes.)

If you want to test it, you'll need to install the QScintilla package from PyPi.

(This plugin will not work with the Windows version, unless sys.path is updated.)

[KevinH]

Code folding can be done in the Inspector under Preview to help you navigate. There are other editors that do code folding as well.

That said, I still don't understand why this makes any sense for a plugin? If you want to use an editor inside Sigil you can take the python code you wrote and tweak it only slightly to accept a filename or path in main and create standalone python code and launch it with "open with" from inside Sigil without every having to launch a plugin.

So I am confused, in what way does a plugin need a gui editor that can't be handled by "open with" inside of Sigil.

[DiapDealer]

Need for it aside, I'm a little concerned with how difficult it might prove to incorporate it in Windows Sigil. We're already delivering a truncated and stripped-down version of PyQt5 that's held together and isolated with QProcess environment variable tweaking. Finding the minimum I need to add back in order to fully support QScintilla could prove time consuming.

[BetterRed]

There's a boatload of Scintilla based text editors, many of which are free, on Windows I use Notepad++ and Bowpad via Sigil's Open With. My primary motivation to use them on xhtml and css is code folding. When I use them I often wonder: "If Sigil were starting development today, would it make sense to use Scintilla/ScIte as the basis of its code editor."

However, I can't see what advantage a Scintilla plugin would offer over Open With, unless one regards having something in the Plugins menu as being significantly superior UI-wise to right clicking the thing you want to edit in the Book Browser. In which case, wouldn't it be easier to add the Open With option to the Edit menu and button bar.

BR

[najgori]

wrong forum. sorry.

[KevinH]

This is not a thread on suggestions for future releases. This thread is about plugin development and developers. Please keep on topic in this thread. Suggestions for new features unrelated to plugins should be done in the main Sigil forum thread.

Thank you.

[Doitsu]

I'm working on a validation plugin for the French grammar/spell checker Grammalecte. If you want to test it with French books, PM me for the beta download link. (I'll release it once the Grammalecte developer releases Grammalecte 1.0.)

Please note that Grammalecte only supports French.

[KevinH]

The Sigil plugin interface is being expanded and updated for Sigil 1.0 and later.

Starting with version 1.0, Sigil will no longer force ebook developers to follow Sigil's standard epub structure. This means that Sigil will no longer force epubs into standard form when first opened. This should allow more advanced developers to create layouts specific to their customer's or reader's needs and prevent breakage of javascript code that depended on the current epub layout.

Therefore a new way of uniquely identifying a file must be used as the filename alone may not be unique.

A book path (aka "bookpath" aka "book_href" aka "bookhref") is a unique relative path from the ebook root to a specific file.

As a relative path meant to be used in an href or src "link", it only uses forward slashes "/" as path separators.

Since all files must exist inside the epub root (the folder the epub was unzipped into), bookpaths will NEVER have or use "./" or "../" ie. they are always in canonical form.

For example under Sigil-0.9.XX all epubs were put into a standard structure. Under this standard structure book paths would look like the following:

    #   OEBPS/content.opf                                                                                               
    #   OEBPS/toc.ncx                                                                                                   
    #   OEBPS/Text/Section0001.xhtml                                                                                    
    #   OEBPS/Images/cover.jpg                                                                                          
    #   ...

and src and hrefs always looked like the following:

                                                              
    #    from Section0001.xhtml to Section0002.xhtml: ../Text/Section0002.xhtml                                         
    #    from Section0001.xhtml to cover.jpg:         ../Images/cover.jpg                                               
    #    from content.opf to Section0001.xhtml:       Text/Section0001.xhtml                                            
    #    from toc.ncx to Section0001.xhtml:           Text/Section0001.xhtml

Under Sigil 1.0 and later, the original epub structure will be preserved meaning that file names like "content.opf" could be named "package.opf", and be placed almost anyplace inside the epub. This is true for almost all files.

So to uniquely identify a file, you need to know either the bookpath of the OPF file itself and the manifest href to the specific file from the OPF, or the direct path from the epub root to the file (ie. its bookpath)

Therefore the Sigil plugin interface for Sigil 1.0 and later has been extended to allow the plugin developer to more easily work with bookpaths, create links between bookpaths, etc.

We will use the terms book_href (or bookhref) interchangeably with bookpath with the following conventions:

                                                                      
    #    - use book_href or bookhref when working with "other" files outside the manifest                                           
    #    - use bookpath when working with files in the opf manifest                                                     
    #    - use either when working with the OPF file as it is at the intersection

Please note, that the old plugin interface will continue to work for all epubs that are in the pre Sigil 1.0 standard form. Sigil will contain a tool to standardize the epub layout if the ebook developer so chooses.

Changes to your plugin code should only be needed if you build links, or access the complete OPF using fixed paths.

Help will be provided to any plugin developer if requested.


Here are the new interface functions:

    # returns the bookpath/book_href to the opf file
    #                                                                    
    def get_opfbookpath(self)
  
    
    # returns the book path of the folder containing this bookpath
    # 
    def get_startingdir(self, bookpath)
 
 
    # return a bookpath for the file pointed to by the href                                                             
    # from the specified bookpath starting directory
    #
    def build_bookpath(self, href, starting_dir)


    # returns the href relative path from source bookpath to the target bookpath
    #
    def get_relativepath(self, from_bookpath, to_bookpath)


    # adds a new file to the *manifest* with the stated bookpath with the provided
    # uniqueid, data, (and mediatype if specified)
    #
    def addbookpath(self, uniqueid, bookpath, data, mime=None)


    # functions for converting from  manifest id to bookpath and back
    #
    def bookpath_to_id(self, bookpath, ow=None)
 
    def id_to_bookpath(self, id, ow=None)


    # returns a sorted folder list for that group                                                                                                       
    # valid groups: Text, Styles, Images, Fonts, Audio, Video, ncx, opf, Misc
    #                                                                           
    def map_group_to_folders(self, group, ow)


    # get file group from its mediatype
    #
    def map_mediatype_to_group(self, mtype, ow)


    # returns true if epub is in Sigil standard format
    #
    def epub_is_standard(self)

[KevinH]

As a follow-up Sigil will soon be releasing a Sigil 1.0 alpha release that supports these new plugin interface methods so that you can test and update your plugins before Sigil-1.0 goes final and is released.

[theducks]

Kevin
Can Sigil 1.x have an option to continue doing it the old way (level structure)? BUT NOT, undo a book with the new structure, or is that impossible to do robustly?

[DiapDealer]

Originally Posted by theducks

Kevin
Can Sigil 1.x have an option to continue doing it the old way (level structure)? BUT NOT, undo a book with the new structure, or is that impossible to do robustly?

I'm not sure I follow.
Continue doing it the old way, but also support alternative structures. Is that what your asking?

Sigil 1.0 will open epubs with the internal structure they were created with. The user then has an option to restructure an epub into Sigil's traditional structure if they so choose. Or they can continue to work on it as is.

Epubs that comply with Sigil's traditional structure (whether created that way, or converted into that structure) should have no issues with any existing plugins. But we'd love it if plugin devs upgraded their plugins (if necessary) to support working with alternatively structured epubs. Others will be willing to help if they run into trouble.

We're not currently offering any way for users to automatically have epubs that are being opened restructured into Sigil's traditional epub structure. That's a one-time menu option they will have to do manually on epubs with different structures after they've opened them.

[KevinH]

If it helps, Sigil 1.0 is designed to not change anything too much for people who do not want to change.

If the user says they do not want full bookpaths in BookBrowser in their prefs (the default), and uses the "Convert Epub to Sigil norm" menu item if and only if they load a non-standard epub from someone else ... almost everything will stay exactly the same.

The only visible differences will be in addition of a few Tools and menu items (like adding a Move context menu item). Even old plugins will continue to work as desired.

All of the new things, only come into play if you want to work with non-standardized epubs. That was never possible in Sigil before but will be now.

Hope this helps,

KevinH

[najgori]

Version 1.0! This is good news! Why is hidden here in plugins?

[DiapDealer]

Originally Posted by najgori

Version 1.0! This is good news! Why is hidden here in plugins?

I think it's been mentioned elsewhere, but we just wanted to give plugin devs some advance notice so that by the the time the pre-release gets tested and (hopefully) the kinks worked out, the transition for plugin users would be smoother when 1.0 does officially get released.

So, we're not hiding it. We just wanted to give the people who need to know some time to adjust accordingly.

But yes ... not forcing all epubs into a mandated files structure was the last stated major hurdle before v1.0.