Scrivener User Manual Corrections

User avatar
nontroppo
Posts: 1067
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Wed Dec 20, 2017 10:09 am Post

§24.22.1: From this thread: viewtopic.php?f=3&t=49854 — there are two issues. The first is the Environment edit description (p.647) is wrong, you cannot edit environment items using key=var. All it accepts is a path fragment that is prepended to path.

The other one is more conceptual:

Instead that file will be held in a hidden temporary location, to be further processed by the command you specify in the fields below.


Is this really what happens? My custom post-processor scrivomatic seems convinced it is being run in the compile folder (it checks its path, STDIN etc.), not a temporary folder...


Finally a very minor thing. The Headers in the manual use XX.X. Title — is that second period necessary?

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Fri Dec 22, 2017 12:00 pm Post

Thanks, I’ll fix these, along with some 3.0.1 stragglers after the holiday break.

Finally a very minor thing. The Headers in the manual use XX.X. Title — is that second period necessary?

Yes. ;) More precisely, I’d rather figure out why spaces are dropped when copying them than changing the stock label.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
nontroppo
Posts: 1067
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Tue Jan 02, 2018 2:36 pm Post

Based on the confusion this user has here: viewtopic.php?f=2&t=50043 — I wonder whether a clearer description of the differences between EPub2/legacy-mobi vs. EPub3/KF8 would be worth including? I ended up referring that user to the blog, but wish I had a more pithy info box or something I could refer them to in the manual...

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 12:54 am Post

In addition to my earlier report of the un-expanded <$include> tag, I also found 3 instances where the text contains "\<$include>" when talking about the tag. See section "10.1.5 IncludingTextFromOtherDocuments", where I believe the intent is to not show that leading back-slash in the compiled output.
Last edited by rdale on Tue Feb 06, 2018 2:04 pm, edited 1 time in total.
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue Feb 06, 2018 11:25 am Post

The 3.0.1 user manual (you’ll need to download it) should be all okay, with the exception of one last remaining instance I found in the front & back matter section.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 2:46 pm Post

AmberV wrote:The 3.0.1 user manual (you’ll need to download it) should be all okay, with the exception of one last remaining instance I found in the front & back matter section.

Concerning the download of the manual, is the extras pack supposed to include the Scrivener manual project? If not, how do I download it? I only see options for PDF, the extras pack (which doesn't contain a project named for the manual) and the iOS tutorial project at https://www.literatureandlatte.com/lear ... ser-guides.
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue Feb 06, 2018 3:55 pm Post

If you download the PDF version for macOS that should be 3.0.1. There were some issue with it being included in the actual update, so I uploaded the update to the server a bit later. The extras pack is just the extras---exercises and samples that are referred to from the PDF.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 4:33 pm Post

So, to be clear... you don't have the Scrivener project for the manual available for download on the support page?
This (from "Compiling with Document Links")...
If you would like to see an example of this in practice, this user manual (available
on our support page) records all keyboard shortcuts as custom metadata in
the menu and shortcuts appendix.

... isn't providing a link to download the project? It's just to help you find the PDF that I'm already reading, and therefore don't need to download? That's a bit confusing to me. I can see the text you've included via the <$include> tag all over the place, though I can't tell which text is provided that way vs. what is in the main document, because I'm only looking at the end result.
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue Feb 06, 2018 5:44 pm Post

So, to be clear… you don’t have the Scrivener project for the manual available for download on the support page?


Nope, not yet.

Ordinarily there would be no need to download the PDF if you already have the software installed, yes. But in this case the 3.0.1 update was released without the revised version of the manual, so you’re still looking at the original 3.0 revision—unless that has since been fixed. The copyright page has the precise revision number toward the bottom. The latest public version is 3.0.1-01b.

That’s a bit confusing to me. I can see the text you’ve included via the <$include> tag all over the place, though I can’t tell which text is provided that way vs. what is in the main document, because I’m only looking at the end result.


Do you mean to say you’ve found cases where it looks like I meant to use the <$include> (rather than just talking about it) but it didn’t work? I think I came across one or two instance of that but they are hopefully all fixed now in the latest PDF.

Everything in this thread in fact, save for the last few items that were mentioned before I went on holiday, should be addressed in the newer PDF.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 6:21 pm Post

AmberV wrote:
That’s a bit confusing to me. I can see the text you’ve included via the <$include> tag all over the place, though I can’t tell which text is provided that way vs. what is in the main document, because I’m only looking at the end result.


Do you mean to say you’ve found cases where it looks like I meant to use the <$include> (rather than just talking about it) but it didn’t work? I think I came across one or two instance of that but they are hopefully all fixed now in the latest PDF.

No, this time I'm being the confusing one. Sorry.

I assume that the text you've added via the <$include> is all over the manual. I can see text that seems to be repeated in a couple of places, as if you used the <$include> tag to duplicate that text… but I have no idea IF you did that, or just copied and pasted the text. Directing the reader to go download the latest PDF ("If you would like to see an example of this in practice…") does not illustrate how to make use of the <$include> tag; it just shows the end result, which is not helpful to someone trying to learn how to properly use it.

Does that make sense? I thought that quote was about seeing how this looks in Scrivener.
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue Feb 06, 2018 8:27 pm Post

Got it!

Oh yes, I used <$include> quite a bit for reals. :) To the point that I even created a custom icon to represent a type of binder item that merely links its content in from another place (I think of it as a “replicant”). I also took to using keywords to tag “master text” items. It’s a nice way of seeing that you’re going to have the text you are editing potentially used in another context (and Bookmark back-links let me know where check), and since I can easily view where this text might end up in the inspector, make sure the text I’m editing fits in seamlessly with all of its intended outputs.

The quote you mentioned earlier however is for something slightly different. For keyboard shortcuts I don’t use <$include> (unless for some reason I need to restate the menu command text in another location), I use <$custom:shortcut>, which gets modified at compile time to <$custom:MacShortcut>, pulling the value of the MacShortcut text string into the document that requested it. When I compile for Windows, the replacement will of course call for <$custom:WinShortcut>. The source text then just has one generic custom metadata request.

ImageWhich, now that I look at it, I notice requires fixing as there is no “Existing Files” menu command, making this an appropriate and topical inclusion to the thread!
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 8:40 pm Post

AmberV wrote:Got it!

... Not quite.

Why are you directing readers to that link? What am I supposed to find there that further illustrates how you use custom metadata for the purpose being described in that section of the manual?
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
AmberV
Posts: 22433
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Tue Feb 06, 2018 8:46 pm Post

Nothing at the moment. Once I get the .zip uploaded there will be a project there. The choice is between going through the whole thing and weeding out references to something that should be there, and then putting them all back in once it is, or working on getting it ready for upload. That's turned out to be a bigger job than I hoped for. Part of the problem is the screenshots---they are all linked out to the file system, and links are absolute not relative, so even if I included the graphics (which measures in the gigs before compression) it would be a bit of a pain to have to fix all of the broken links. I'm not sure what the best solution is there.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1340
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Tue Feb 06, 2018 10:34 pm Post

AmberV wrote:Nothing at the moment. Once I get the .zip uploaded there will be a project there.

Okay, so I'm not going blind... or my lack of ability in locating something useful isn't due to failing eyesight at least. :|

AmberV wrote: The choice is between going through the whole thing and weeding out references to something that should be there, and then putting them all back in once it is, or working on getting it ready for upload. That's turned out to be a bigger job than I hoped for. Part of the problem is the screenshots---they are all linked out to the file system, and links are absolute not relative, so even if I included the graphics (which measures in the gigs before compression) it would be a bit of a pain to have to fix all of the broken links. I'm not sure what the best solution is there.

Oy, that's a tough one. One thing to consider, if you're willing to re-work all those paths (I know, that's a big "if"), is to dump them all into a sparsebundle/DMG. I believe, when mounted, they always get attached to /Volumes, and should always resolve to the same path on any Mac. Doesn't do the Windows folks any good, but I wonder if there's any solution to cross-platform compatibility with external resources... other than talking Keith into making Scrivener able to compile images from hosted webdav/HTTP locations.

Sounds like too much work to me now that you bring it up, unless reworking your external content storage system solves some other issues for you. Maybe it would be better to just keep expanding the "extras" with example projects that use excerpts from the manual itself to give some context?
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".