Thanks, I followed your instructions then put it in the trash but didn’t delete that group after clicking “Only database”
there is a little lock showing in the group.
Unlock it from the Data > Mark menu.
Thank you
This is much. better. thank you
So every time there is a new DevonThink version, you have to delete it
1 Like
Assuming that you don’t want to look up something in an old version of DEVONthink’s help: yes
1 Like
This is a really great idea. Having the help indexed is nice. I got tired of manually copying it and indexing it though. I found a way that I prefer.
Use the help bundle directly from DEVONthink
There is value in simply using the help bundle directly. To do this easily, the help bundle would need to be altered slightly. I will explain later. (See Why would the help bundle need to be modified?)
Without changing the help bundle we can still call into Apple help using its URL schema, shown here.
Here is how I use it
I added the following markdown links in my DEVONthink database. They work fine on my system, with the default help bundle (the help installed with DEVONthink).
NOTE: The links do not appear to work from the discourse page so to test them you will have to copy them locally.
Link to the DEVEONthink help
[ DEVONthink Help](help:openbook=DEVONthink%20Help)
The URL looks like this.
help:openbook=DEVONthink%20Help
The result looks like this.
Link to search DEVONthink help
We will search for the words search prefix in the DEVONthink help.
Search for “search prefix” in DEVONthink Help
[Search for "search prefix" in DEVONthink Help](help:search='search%20prefix'%20bookID='DEVONthink%20Help')
The URL looks like this.
help:search='search%20prefix'%20bookID='DEVONthink%20Help'
The result looks like this.
Link directly to the search prefixes page in the appendix
The Search Prefixes appendix page
[The _Search Prefixes_ appendix page](help:anchor='appendix-searchprefixes'%20bookID='DEVONthink%20Help')
The URL looks like this.
help:anchor='appendix-searchprefixes'%20bookID='DEVONthink%20Help'
The result looks like this.
Why would the help bundle need to be modified?
The last link is the kind of thing that I find the most valuable. I want to link to a particular page. Often I want to link to a particular part of a page. The way this is done is with anchor links. Anchor links need to be defined, and used, in the help. The best that I can tell, they are not (yet). See the explanation from Apple here.
So if anchors are not defined, how did the last link work? I did a little investigation and made a lucky guess.
The last URL looks like.
help:anchor='appendix-searchprefixes'%20bookID='DEVONthink%20Help'`
If I capture the search prefixes link from the find page of the help I get this URL.
file:///Applications/DEVONthink%203.app/Contents/Resources/DEVONthink.help/Contents/Resources/pgs/appendix-searchprefixes.html
This is not what I want because it is path dependent. The anchor link does not depend on the path because it uses the help book identifier, registered with macOS, and the page identifier rather than the page file name. DEVONthink’s help registration id, DEVONthink Help, would likely be more stable and static across editions and versions than the path.
To get the URL I opened the page with the link in the macOS help viewer. (Click help in DEVONthink)
Then I right clicked on the link and selected Copy Link.
When I opened the help bundle, with view package contents, I could see the layout of the help. Looking in the sources I did not seen any anchors I could use. Perhaps the index provides anchors for each page? The page I wanted was in the pgs path. That can be seen both by examining the package contents and be deconstructing the file-path link copied above.
...Contents/Resources/pgs/appendix-searchprefixes.html
So I just put the of the file as the anchor
...anchor='appendix-searchprefixes'
Proposal
In-page anchors
Please add in-page anchors to the DEVONthink help bundle and change the existing link URLs to use them. This way when we copy the links in the help we get anchor links rather than path-dependent links. This also permits us to deep link into particular parts of pages rather than just the page.
This script indexes DEVONthink’s help and renames the records properly. There’s nothing more to do than running the script. Did you try it?
Linking to help pages is interesting, however it‘s relying on macOS‘s help viewer which in general is bad in searching. I don’t quite get why one would use the same bad app just in another way. This approach also misses the point of using DEVONthink‘s features, e.g. its search capabilities, See Also or replicating.
I want one consistent way that I may keep directly linked notes, Zettelkasten style, with any macOS help file. I do not want to maintain copies that I must update after an upgrade. Searchable, indexed, help files would be fantastic.
I need to try your script.
Does the script produce something that works the same as other indexed files in DEVONthink? Do Update Indexed Items and the Repair Database actions work the same for the help file? I wonder if it could use the API to find help files from the registry (perhaps when clicking on an application from the finder)?
I see. I’ve indexed duplicates of each important app’s help bundle, however I do not link to them, I just use DEVONthink’s search to quickly find what I’m looking for. I don’t update them with every new app version but read the release notes instead. If there are new features I want to use or existing ones have changed I update the indexed help.
So we have different needs. My script does use a duplicate of DEVONthink’s help bundle and the indexed records need to be deleted after an update, so that’s not what you’re looking for.
Do you mean it would be useful to index the original help bundles from inside an app’s package? If so take a look at the script @BLUEFROG posted in this thread. Obviously it needs to be used with care as you would be dealing with original files.
I do not encourage my initial approach due to the use of the original files. It was really more academic than practical.
@pete31’s approach with duplicated and indexed files is safer and still useful for periods of time as the documentation is only updated after releases.
1 Like
Yes, exactly. I want to search and link help bundles in their original locations.
I understand it’s far more comfortable to index a help bundle once but I don’t think it’s a good idea. There’s always the risk of user error and then you might and up with a broken app. But of course it’s up to you.
Played around with your idea, especially I looked for anchor links in my indexed help bundles and other apps. Seems not a single app out of over 150 that I tested got them. Are you aware of an app that got anchor links? I’d like to verify the script I used with an app that definitively got anchors.
Not sure if it’s useful at all, however while playing around I came up with a script that can search in one app’s help or in help of all apps that are registered with a help bundle. It obviously doesn’t make sense to use the script as it is, however if one puts it in e.g. an Alfred workflow it could be useful to someone.
-- Search in macOS's help viewer
use AppleScript version "2.4"
use framework "Foundation"
use framework "AppKit"
use scripting additions
property searchAllHelpBundles : false
set theQuery to "search prefixes"
set theApp_Name to "DEVONthink 3"
try
if not searchAllHelpBundles then
set theApp_Path to POSIX path of (path to application theApp_Name)
set theBundle to current application's NSBundle's bundleWithPath:theApp_Path
set theBundle_HelpBookName to (theBundle's objectForInfoDictionaryKey:"CFBundleHelpBookName")
set theHelpManager to current application's NSHelpManager's sharedHelpManager
theHelpManager's findString:theQuery inBook:theBundle_HelpBookName -- search one help bundle
else
set theHelpManager to current application's NSHelpManager's sharedHelpManager
theHelpManager's findString:theQuery inBook:(missing value) -- search all help bundles
end if
on error error_message number error_number
if the error_number is not -128 then display alert "Oh no" message error_message as warning
return
end try
Wow, thank you! I will check it out.
The Skim app has useful anchor links defined. (I think I have it installed from macports or homebrew.) Here is a working link example.
[Finding text](help:anchor='Finding-text-in-a-PDF-file'%20bookID='Skim%20Help')
The links are defined in the pages so one could do in-page linking but are not really used with help URLs in the help document. This is disappointing.
Here is an example URL from where the help uses a file link where they could be using an anchor link.
file:///Applications/Skim.app/Contents/Resources/Skim.help/Contents/Resources/en.lproj/SkimHelp_48.html#Automating-tasks-with-AppleScript
What specifically might break? Would we be at risk breaking the app with the help or DEVONthink, or both? If the macOS help viewer can not resolve or understand a link, it simply gives an error saying as much.
I also notice that not all apps actually use help bundles for their help. An example is Scrivener, which uses PDF. I still plan to be able to search the help, in-place, for selected applications, this simply adds complication. I will try to solve this for apps that use help bundles first, then move on to on-off cases.
I think between what you and @BLUEFROG have built, I should be most of the way to my goal.
Okay. I think I understand the issue with indexing the help in-place. While it is searchable by DEVONthink, it is also editable. Edits would damage the help.
It looks like it would be possible to mark something as locked but I suspect that does not prevent the item from being editable from DEVONthink. There would need to be some kind of enforced read-only attribute, to make it impossible to edit from DEVONthink.
EDIT:
I just read through the thread again. Making a copy of the help makes sense now. I am not giving up on in-place permanently, but to do it safely it appears that DEVONthink would need to be altered.
If I am not going to read the help bundles in-place, then I no longer care about keeping them as help bundles. PDF files would work better for me.
I will see about converting them from help bundles to PDF. (I do not think your script is doing this, but I am not sure.) I should be able to alter the links to be relative during that conversion. Then when the links are used (or a search is performed) they will open in the PDF the same way that they work with other PDFs in DEVONthink.
Exactly. However it is sufficient to lock the files in Finder. That’s what I’m doing in the script that indexes a duplicate, but there it is done in order to be able to rename the records in DEVONthink without changing their filenames as this of course would break all links.
It might be possible to lock the files inside the original help bundle but I never tested it.
Thanks for Skim, I’m currently testing if and how the anchors could be accessed via script. It seems either does Skim not follow Apple’s instructions and / or I’m trying it not correctly. Not giving up yet 