I'm putting together a user guide for a complicated database for creating teaching schedules, assigning faculty to classes, and coding the classes with payment amounts. In short, a narrative that is on continuous pages (about 50 of them) would be difficult to read and use. I would prefer to have an app that would allow me to make 50 self-contained pages, each with several paragraphs and maybe a table, and have all of these pages hypertext-linked to one another but not outside of the document.

All modern word processors seem to have this sort of functionality, but the writing still exists in what Neil Larson used to call a "toilet roll" document. I would prefer a *file* that allows me enough freedom between pages so I can sort them alphabetically, but not have separate files for all of the pages. Like Tinderbox, I would like to be able to drag the pages into alphabetical order, or possibly group them, not for the user's benefit, but for my benefit in organizing the topics.

Tinderbox and StorySpace (fraternal twins from Eastgate) seem to have possibilities, but so little is written about them, I'm not sure. VooDooPad can do the hypertext, but can the file serve as a free-standing document with internal links, with no need for a runtime solution? I've also considered Filemaker Pro with lots of buttons and scripts sending the user around. And some of the PDF editors seem to have some of this capability.

Have any of you had this challenge and found something that is self-contained (needs no app to be bought by the end user)? I'm hoping for something that would allow me to paste tables and figures on the pages as well.

If you are creating a file for distribution, then most likely you want to give your readers something "standard" -- e.g., like a PDF.

Futzing around with Tinderbox or Storyspace might be interesting for developing your narrative, but export to PDF with linked pages intact can be more effort than it's worth. I use Tinderbox extensive, have for years, but decided a long time ago that it's a time suck when it comes to producing high quality exports that I am willing to give to other people. Love the app, but it's like having to invent new software for every exported document.

But why not use Word (or Pages -- if you're on a Mac). The linking you want is easy to do -- the export is a snap.

For writing use help documentation for https://www.easydatatransform.com/ and https://www.perfecttableplan.com/ I use the excellent https://www.helpandmanual.com/ It can output in PDF, CHM, HTML and various other formats. It only runs on Windows. Might be worth a look.

Thank you for the insight Paul. I thought about doing all of the pages in Tinderbox (w/o hypertext), organizing them alphabetically, and then dropping them into Pages or Word. Whatever I use, it will have to be a PDF file. I think that Word relies on bookmarks instead of note names. I'll need to figure out how best to do that.

I do have Windows by way of Parallels, so that isn't completely off the table. I'll give your suggestions a look. They *sound* promising.

Andy Brice wrote:

For writing use help documentation for
https://www.easydatatransform.com/ and https://www.perfecttableplan.com/
I use the excellent https://www.helpandmanual.com/ It can output in
PDF, CHM, HTML and various other formats. It only runs on Windows. Might
be worth a look.

I also write software documentation, and moved away from Word a few years ago to markdown and then, more recently, to asciidoc. If you are comfortable writing in markdown, there are many online tools that you can use to create, collaborate, and publish/deploy your help files (both HTML+PDF). Here are a few of my favourites. (Note that "ssg" stands for static site generator.)

- Typora - https://typora.io/ - for offline writing/notetaking
- HackMD - https://hackmd.io/ - for online writing/notetaking
- MkDocs - https://www.mkdocs.org/ - ssg for documentation sites
- Docusaurus - https://v2.docusaurus.io/ - ssg for docs by Facebook

If you want more control over your content (i.e., images, callouts, tables, admonitions, footnotes, etc.), check out asciidoc:

- Asciidoctor - https://asciidoctor.org/ - documentation publishing toolchain (HTML/PDF)
- Asciidoctor Tutorial - https://www.vogella.com/tutorials/AsciiDoc/article.html

Asciidoctor publishes a "toilet-paper-role-with-toc" webpage and PDF (if that's what you want); however, I break the content into chapters and then combine them as needed. As an author/writer, I appreciate the added features that Asciidoctor provides, yet it's as simple as markdown if that's what you want.

Another benefit of markdown and asciidoc is that text-based source files allow me to use GitHub/GitLab for version control and quick/easy updates and deployments. I've even moved my outlining/notetaking away from Evernote to markdown-based Joplin (https://joplinapp.org/

Hope that proves helpful.
Glen
p.s. Over the past several years, I have been moving my ConnectedText content to markdown, since I don't ever want to worry about being in a "walled-garden" again. Something to consider with documentation as well!

Jeffrey

To clarify, I am only recommending https://www.helpandmanual.com/ The other 2 applications are my products that I use Help & Manual to write the documentation for.

Jeffery Smith wrote:

I do have Windows by way of Parallels, so that isn't completely off the
table. I'll give your suggestions a look. They *sound* promising.

Andy Brice wrote:
For writing use help documentation for
>https://www.easydatatransform.com/ and
https://www.perfecttableplan.com/
>I use the excellent https://www.helpandmanual.com/ It can output in
>PDF, CHM, HTML and various other formats. It only runs on Windows.
Might
>be worth a look.

I did understand that. And it is helpful to see what the finished product looks like. I'm not sure I can justify the price of your recommended product (this manual may be the last piece of paid work I do).

Andy Brice wrote:

Jeffrey

To clarify, I am only recommending https://www.helpandmanual.com/ The
other 2 applications are my products that I use Help & Manual to write
the documentation for.

Jeffery Smith wrote:
I do have Windows by way of Parallels, so that isn't completely off the
>table. I'll give your suggestions a look. They *sound* promising.
>
>Andy Brice wrote:
>For writing use help documentation for
>>https://www.easydatatransform.com/ and
>https://www.perfecttableplan.com/
>>I use the excellent https://www.helpandmanual.com/ It can output in
>>PDF, CHM, HTML and various other formats. It only runs on Windows.
>Might
>>be worth a look.

Thanks for the replies. I fiddled around with several things, and I may untimately use what I have used in the past for this sort of project...Filemaker Pro. I even used Nutshell, the distant ancestor of FMPro over 3 decades ago. I make a framework for the title, writing, and any pictures on a template, fill in the information on one screen, and make another layout to print to PDF. But I'm also going to use Adobe Acrobat to create links in the manual that jump to major pages referenced.

Hey Jeffery,

Before committing to what sounds like a remarkably clunky process (I use and adore FM Pro, but would never use it for a project like the one you’ve described, not least because of the post-editing required), I’d suggest you look at Versatil Markdown in the Mac App Store, which is a very powerful editor (a bit like Typora on steroids). It also exports to PDF, HTML or Web Archive format, which seems to me ideal for something like help files or hypertext notebooks.

It also supports document aliases (transclusion, as I was kindly reminded in a previous post). It’s not well known - not because it’s not actually very easy to use (it is), but perhaps because it comes across first and foremost as a programmer’s tool (it can be).

Which reminds me that it would also be worthwhile exploring Quiver as a possible solution (now that does describe itself as a programmer’s notebook, but is a lovely piece of software, although the author appears, alas, to have given up on developing an iOS version). Quiver (also in the Mac App Store) also has an impressive range of output options, including PDF, HTML, Markdown, JSON and others.

Cheers!
Bill

Jeffery Smith wrote:

Thanks for the replies. I fiddled around with several things, and I may
untimately use what I have used in the past for this sort of
project...Filemaker Pro. I even used Nutshell, the distant ancestor of
FMPro over 3 decades ago. I make a framework for the title, writing, and
any pictures on a template, fill in the information on one screen, and
make another layout to print to PDF. But I'm also going to use Adobe
Acrobat to create links in the manual that jump to major pages
referenced.

I will check them out. I have never liked LaTEX, and need an editor. In fact, I'll look at several of them.

Thanks much!

Jeffery

MadaboutDana wrote:

Hey Jeffery,

Before committing to what sounds like a remarkably clunky process (I use
and adore FM Pro, but would never use it for a project like the one
you’ve described, not least because of the post-editing required),
I’d suggest you look at Versatil Markdown in the Mac App Store,
which is a very powerful editor (a bit like Typora on steroids). It also
exports to PDF, HTML or Web Archive format, which seems to me ideal for
something like help files or hypertext notebooks.

It also supports document aliases (transclusion, as I was kindly
reminded in a previous post). It’s not well known - not because
it’s not actually very easy to use (it is), but perhaps because it
comes across first and foremost as a programmer’s tool (it can
be).

Which reminds me that it would also be worthwhile exploring Quiver as a
possible solution (now that does describe itself as a programmer’s
notebook, but is a lovely piece of software, although the author
appears, alas, to have given up on developing an iOS version). Quiver
(also in the Mac App Store) also has an impressive range of output
options, including PDF, HTML, Markdown, JSON and others.

Cheers!
Bill

Jeffery Smith wrote:
Thanks for the replies. I fiddled around with several things, and I may
>untimately use what I have used in the past for this sort of
>project...Filemaker Pro. I even used Nutshell, the distant ancestor of
>FMPro over 3 decades ago. I make a framework for the title, writing,
and
>any pictures on a template, fill in the information on one screen, and
>make another layout to print to PDF. But I'm also going to use Adobe
>Acrobat to create links in the manual that jump to major pages
>referenced.

Versatil Markdown looks really nice - thanks for the link.

It’s a good app - but I’ve found that unlike Typora, it doesn’t have a universal search function. Which is annoying.

Another macOS app it’s well worth exploring for this kind of requirement is MacJournal, currently available free of charge. You can create a large software manual and then export it to various formats, including RTF, PDF, HTML, ePub and others.

The app itself is extraordinarily powerful, with all kinds of unexpected features. It isn’t really journaling software at all - it’s more like a kind of all-round information manager. The search function alone is hugely powerful.

Personally, I use it to keep track of all kinds of business processes, which I then regularly export as separate files into folders on a shared drive. But MacJournal is also capable of exporting multiple notes (in folders) as a single enormous file - or you can export individual folders as a single file if you prefer. The only shortcoming I’ve discovered here is that the resulting PDF file won’t pick up on internal links you may have set up between notes. However, if you choose the HTML export instead, it does preserve internal links. Sadly, the ePub export is currently registering as “corrupt”.

The other way of producing a large PDF file of all your notes is the “Print Journal…” option.

I thought MacJournal was no longer under development, but an update appeared last week (to remedy some issues under macOS Catalina), so that’s encouraging!

If you’d like to try it, you can download it for free from Dan Schimpf’s website at https://danschimpf.com

Cheers,
Bill

Sorry, I should make it quite clear that you can choose to export (a) an individual note, (b) a folder of notes or (c) the entire journal.

If you export the entire journal, MacJournal will create the individual subfolders as folders on disk without prompting, so you can recreate your journal structure in your file system as a hierarchical collection of documents (in RTF, HTML, PDF, ePub, OpenDocument, Word, Markdown and other formats, including a few I’ve never heard of like iPod Notes).

I’ve not actually come across anything quite like this on any platform (apart, perhaps, from DEVONthink). I used to use a very nice HTML editor in Windows to generate business procedures. It was freeware, and could be used as both editor and reader. But this was over 10 years ago, and I can’t for the life of me remember what it was called…

Cheers!
Bill

I'm downloading it right now. I was a paid user of MacJournal until they seemed to abandon it. I recall reading that the author rescued his baby and breathed life into it. It may be a great app to use for my purposes.
Thanks!