Is Sigil 072 the latest User Guide?

[DiapDealer]

Originally Posted by eschwartz

In fact, the current user's guide was uploaded at the old googlecode site, as the sigil.web git repository (and was used as an online version of the guide).

You could upload that as a Sigil-ebook.github.io repo, to get the guide back online, and then work from there.

Now that's very interesting. I wasn't aware of the Github Pages feature. Thanks for pointing it out! I was looking at the wiki provided by Github, but it doesn't look nearly as flexible. Plus it would be much easier to give others access to edit the guide (without having to give access to the actual Sigil code repo). I'm assuming one could fork and submit pull requests as normal, too.

[eschwartz]

Of course, it's just a regular repo, after all...

[Notjohn]

Originally Posted by eschwartz

In fact, the current user's guide was uploaded at the old googlecode site, as the sigil.web git repository (and was used as an online version of the guide).

Ah, so that's why the online version disappeared? I sometimes referred to it when it was online, but I have never opened up the epub version although I've downloaded it more than once. It just seems more natural, if I am working on an epub in Sigil, to go online for help, rather than open another iteration of Sigil to get what is essentially an editing view, not a reading view.

[DiapDealer]

Originally Posted by Notjohn

It just seems more natural, if I am working on an epub in Sigil, to go online for help, rather than open another iteration of Sigil to get what is essentially an editing view, not a reading view.

You don't have to open the guide in Sigil. You could open it in any epub reader--even one that's a browser plugin if that's your preference. The point is to give people both a local and an online resource to choose from. The online resource would be as much about providing a way for people to collaborate on editing the guide (in a standard version control environment) as anything. That Github Pages woould also serve that content to readers is icing on the cake.

[Doitsu]

@DiapDealer & @KevinH: I found out that it's relatively easy to generate a Qt help file from the user guide without any code changes, except for converting non-ASCII characters to HTML entities.

All you'd have to do is, unpack the user guide, copy a Qt help project file to the OEBPS folder and run the Qt help compiler.

To generate the help file:

1. Unpack the updated user guide epub file.
2. Copy sigilhelp.qhp to the OEBPS folder.
3. Go to the OEBPS folder and run the following command:

qhelpgenerator sigilhelp.qhp -c -o sigilhelp.qch

To preview the Qt help:

1. Open Qt Assistant.
2. Select Edit > Preferences.
3. Select Documentation > Add > sigilhelp.qch

(I created a Qt help file and attached it and the help project file.)

Note that the existing user guide contains the following non-ASCII characters that need to be converted to entities before running the help compiler:

copy, mdash, rarr, ldquo, rdquo, rsquo, rarr and ge

I used DiapDealer's ShadyCharacters plugin to convert them to entities. Here's my plugin preferences file:

Spoiler:

{
  "matrix": {
    "ge": [
      "0x2265",
      "≥"
    ],
    "zwj": [
      "0x200D",
      "*"
    ],
    "shy": [
      "0x00AD",
      "*"
    ],
    "zwnbsp": [
      "0xFEFF",
      ""
    ],
    "nbsp": [
      "0x00A0",
      "*"
    ],
    "rdquo": [
      "0x201D",
      "”"
    ],
    "thinsp": [
      "0x2009",
      " "
    ],
    "rsquo": [
      "0x2019",
      "’"
    ],
    "rarr": [
      "0x2192",
      "→"
    ],
    "nnbsp": [
      "0x202F",
      " "
    ],
    "mdash": [
      "0x2014",
      "—"
    ],
    "wj": [
      "0x2060",
      "⁠"
    ],
    "ndash": [
      "0x2013",
      "–"
    ],
    "ldquo": [
      "0x201C",
      "“"
    ],
    "copy": [
      "0x00A9",
      "©"
    ]
  }
}

(Not all of the entries in the list were actually used.)

and here's the corresponding Sigil.ini section:

Spoiler:

preserve_entity_codes=\xa9\x2014\x2019\x201c\x201d\x2192\x2265\xa0
preserve_entity_names="©", "—", "’", "“", "”", "→", "≥", " "

I don't know how difficult it would be to add Qt help viewer support to Sigil, but it couldn't hurt to investigate this idea.

[CalibUser]

Hi,
Although I have not had time to proof read the guide, I thought I ought to report what I think is an error in the section "Advanced Find & Replace – Regex".

The following find expression is given in the text:

<p>\sCHAPTER\s(\d+)\s</p>

and is explained correctly as follows:

• <p> – Look for a starting paragraph tag.
• \s – Regex code to match any white space (blanks, tabs, etc.).
• CHAPTER – Match the word CHAPTER (Regex is case-sensitive by default).
• \s – Regex code to match any white space.
• (\d+) – Regex code to match any number of digits in a row and remember them.
• \s – Regex code to match any white space.
• </p> – Look for an end paragraph tag.

However, the regular expression \s requires that one white space is present in the appropriate places, so the application of this expression to the following examples given in the guide will not work:

<p>CHAPTER 7</p>

and

<p> CHAPTER 14</p>

[For some reason only one space shows when this is put on the forum page although I tried to insert several spaces in front of CHAPTER and several spaces after CHAPTER to match the example in the guide]

The correct expression to find the text in this example should be:

<p>\s*CHAPTER\s*(\d+)\s*</p>

This is similar to the one given in the guide except I have placed an asterisk after the \s. The explanation of this updated expression is:

• <p> – Look for a starting paragraph tag.
• \s – Regex code to match none, one or more white spaces (blanks, tabs, etc.).
• CHAPTER – Match the word CHAPTER (Regex is case-sensitive by default).
• \s – Regex code to match any white space.
• (\d+) – Regex code to match any number of digits in a row and remember them.
• \s – Regex code to match none, one or more white spaces
• </p> – Look for an end paragraph tag.

Perhaps it may be useful to capture a list of errors (if there are any more) in this thread to help when the guide is updated?

[BetterRed]

Originally Posted by CalibUser

[For some reason only one space shows when this is put on the forum page although I tried to insert several spaces in front of CHAPTER and several spaces after CHAPTER to match the example in the guide]

@CalibUser - wrap the regex expressions and HTML code in BBCode code tags, simple way is to select text and click the '#' in the advanced editor tool bar eg:

<p>       CHAPTER 7</p>
<p>\s*CHAPTER\s*(\d+)\s*</p>

Then you'll get the WYTIWYG effect

BR

[DiapDealer]

@CalibUser: You're correct. Though the Sigil guide is not intended to be an exhaustive regex guide, we certainly shouldn't be including incorrect examples. Unfortunately, until we get an updated guide into some sort of CVS system, collaborrative corrections/additions are going to be a little clumsy.

[xingenter]

Originally Posted by DiapDealer

Could you possibly point out anything less relevant than that?

If you're not offering to work on the guide yourself, perhaps you could refrain from criticizing the volunteer work of others. Thanks.

I don't think any offence was meant and the information could be useful if taken as such.

[CalibUser]

Originally Posted by BetterRed

wrap the regex expressions and HTML code in BBCode code tags, simple way is to select text and click the '#' in the advanced editor tool bar

Thanks for this tip, BetterRed

[DiapDealer]

Originally Posted by evilmrb

I don't think any offence was meant and the information could be useful if taken as such.

Though you're responding to a month's-old exchange, I think it's important to understand that Jon is historically prone to dwelling on personal pet-peeves and subverting threads to push his own personal (and often utterly unrelated) agendas. I was merely trying to head him off at the pass.

[Tex2002ans]

I spent some time to go through the Sigil manual in Post #23 and updated it.

I attached it to the end of this post:

Changelog (2018.04.17)

New

(Doitsu helpfully pointed these out)

• Edit > Preferences... > Appearance > Menus > Main Menu Icon Size
• Edit > Preferences... > General Settings > Number of Clipboard History Items
• Edit > Preferences... > Spellcheck Dictionaries > Check Numbers
• Edit > Preferences... > Plugins (Assign as Plugin 4 + Assign as Plugin 5)

Changed

• Typo Corrections
• Cleaned up the temporary "deleted" and "new" styles
• Some Code Consistency
  
  • Menu Items now consistently use the "menuitem" class
    
  • Corrected a few monospaced code examples
    
• Normalized some text
  
  • epub/ePub -> EPUB, mobi -> MOBI
    
  • Smartened Quotes
• Removed 3 unused images.
• Tweaked/Updated a handful of words
  
  • "Python 3.4" -> "Python 3.5.2", etc.

[DiapDealer]

Oh, wow! Thanks. Great work!

I hate to criticize at all, but I would point out that the links to the Building on Linux documentation are a tad out of date. The "Cutting Edge" instructions have become the standard (Building_on_Linux.md) instructions, and the original standard instructions have become Building_on_older_Linux.md. So one link currently goes to incorrect instructions, and the other link is broken.

I've eliminated the use of phrases like "Legacy" or "Cutting Edge."

But if we incorporate this new edition of the manual (and I think we'd be crazy not to), I'd probably make a few changes to the Linux installation section in general. So that's no real issue.

Thanks again!

[Tex2002ans]

Originally Posted by DiapDealer

Oh, wow! Thanks. Great work!

Originally Posted by DiapDealer

I hate to criticize at all, but I would point out that the links to the Building on Linux documentation are a tad out of date. The "Cutting Edge" instructions have become the standard (Building_on_Linux.md) instructions, and the original standard instructions have become Building_on_older_Linux.md. So one link currently goes to incorrect instructions, and the other link is broken.

I've eliminated the use of phrases like "Legacy" or "Cutting Edge."

Yeah, a few parts of the guide are a little crusty.

I didn't check URLs or do any sort of major rewriting. I don't think anyone could handle a Tex-written Sigil manual... it would be a 1000-page tome!

[Hitch]

Originally Posted by Tex2002ans

Yeah, a few parts of the guide are a little crusty.

I didn't check URLs or do any sort of major rewriting. I don't think anyone could handle a Tex-written Sigil manual... it would be a 1000-page tome!

BTW...

Vis-a-vis online help and manuals, and all that, I'm using a new-to-me product called Help+Manual, https://www.helpandmanual.com/ and this thing simply ROCKS my socks off. It's designed to generate online help (CHM) files, that you can slap on a website, but more importantly, you can ALSO output the help to PDF manuals, ePUB and MOBI formatted eBooks. You can use conditionals (media queries), etc. It's smoking. I've had some interaction with the founders/developers, and they would fit right in here with we of the Geeky Clan. Great guys, and you cats know I don't say that lightly or hand out accolades like free candy.

IF I had the time, to do this for you, I'd put the Sigil User guide in it. Actually...you know, Tex, if you wanted to DO the guide's guts, I could put it in the format, if that would help. That's something I could probably scrape up some time for...although, I guess then, the question is, where would it GO? Hmmph. Maybe I should shut up...

Hitch