Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Documentation and Tutorials >> User manual

Message started by maurice on Jan 3rd, 2010, 4:47pm

Title: User manual
Post by maurice on Jan 3rd, 2010, 4:47pm

Any chance of having the old Tinderbox User's Manual back in the pdf form used until 4.7? The new Tinderbox Help seems less user-friendly: it finds documents containing your search term, but you then have to read through each of those documents, often several pages long, to hunt for the occurrence of that term. With the pdf each occurrence of the search term was hilighted.

Title: Re: User manual
Post by indro on Jan 3rd, 2010, 10:38pm

Can I second this request too. A pdf version would be much appreciated.

Title: Re: User manual
Post by Mark Anderson on Jan 4th, 2010, 4:00am

FWIW, the manual is undergoing change in an attempt to make it easier to keep up to date. In the past it was mastered in a offline format that  make even small updates a big task. Currently, the v4.7 manual (ported into a TBX document) is being updated/improved for v5.x. It's a shame Mac Help system doesn't support Safari's (WebKit's?) in-pace find/highlight feature.

In principle each resulting HTML Help page could be 'printed' to PDF and then concatenated into a single PDF; the labour-intensiveness is an issue though there's probably a tool/automator out there for such a task. The PDF could be then made available as a download for those that wish it (no point in shipping two versions in the app).

In the meantime, I wonder if there's a URL on the Eastgate site where users who need it could grab the v4.7 PDF.

I'd be interested to hear the sort of terms with which previous posters to the thread are having difficulties as it might help inform the Help re-write.

Title: Re: User manual
Post by maurice on Jan 4th, 2010, 6:52am

Thanks Mark. As far as grabbing the old 4.7 manual, that's easy enough for anyone who happens to still have a copy of Tb 4.7. You can open the manual from the Help menu and then save the pdf to whatever location you like.  Of course, it doesn't cover the v 5 changes.

Couldn't the manual simply be maintained in a single ordinary word processor document, kept up to date in that form, and instantly converted into a pdf to publish?  

To me, the Help system is pretty much unusable. If, for example, I want to refresh my memory on "keyattributes", I can instantly find the 4 references to that term in the pdf. If I search for the same term in Help I get 3 documents, the first of which is the equivalent of 15 pages in the pdf. The 2nd document is another 15 pages. The 3rd document is 26 pages. There is no indication of where in any of these 3 documents the term appears - or whether each document has a single reference to the search term or multiple references. You basically have to read through the equivalent of 56 pages of the manual to discover the references.  Each time I've tried to look anything up I've given up without finding what I need. I don't think this can be addressed by clarifying the text itself...

Title: Re: User manual
Post by Mark Anderson on Jan 4th, 2010, 10:48am

Interesting. There are three separate issues here. Searchability, granulatity of the Help and the source document format.

Moving the master doc back to Quark (as it was) or a Word DOC strikes me as a step backwards.  Having a TBX as the master document is a big step forward IMO (having had significant input to both processes. It also offers the opportunity to export to different formats.

Having more HTML pages in the Help might give better granularity but bloats the size of the app's Help on disk.

However, it should be possible to export the TBX content as paginated HTML that can then be saved as a PDF covering both bases.

Title: Re: User manual
Post by Mark Bernstein on Jan 4th, 2010, 11:19am

A further torque is that longer pages make the Table Of Contents and navigation sidebar easier to comprehend....

Title: Re: User manual
Post by maurice on Jan 4th, 2010, 3:53pm

Thanks Mark, a pdf would be much appreciated, though it sounds like it would be a lot of work to produce one...

Title: Re: User manual
Post by Rigas Arvanitis on Jan 9th, 2010, 9:23am

Why not have the help as a Tinderbox document itself?

Title: Re: User manual
Post by maurice on Jul 17th, 2010, 2:05pm

Many thanks for the new pdf manual - much appreciated!

Title: Re: User manual
Post by linn on Jan 10th, 2011, 9:20am

I recently got Tinderbox 5.7.1 and downloaded what I thought was the correct Users' Manual (which is entitled Tinderbox v5 Manual - Table of Contents" on p. 1 of 104). Do I have the right manual? If not, where can I get the correct one?
If I do have the current manual, it seems to me that pp. 95-101 have the same information as pp. 89-95. The difference is that the later pages have some headings that the first batch of pages lack although the information is the same in both places (e.g. Conditional Assignment, see p. 89 and 95, respectively). However, I wonder (because I have no programming background) if some headings in the second batch were meant to have more text (e.g., Date Functions of p. 97), or were intended as headings for single-topic headings below them?
   Will I miss something if I simply black out (ignore) pp. 95-101?


Title: Re: User manual
Post by Mark Bernstein on Jan 10th, 2011, 9:32am

I'm on jury duty today, so I can't check immediately.  All things being equal, though, the HTML version of the manual in the help menu is likely to be slightly cleaner and more up to date than the PDF download.

Were working on streamlining this.

Title: Re: User manual
Post by Mark Anderson on Jan 10th, 2011, 10:36am

In the meantime - other than for the general narrative of the manual - you can use aTbRef** which is definitely is up to date.

** albeit only in HTML form but you can download the site's source TBX and export your own local HTML copy if you spend long periods offline.

Title: Re: User manual
Post by linn on Jan 10th, 2011, 4:05pm

Hi, Mark & Mark,
Mark B.--Thumbs up for doing jury duty.

Mark A. Since I'm still learning Tinderbox (really, I celebrated when I changed my first note color!), I work with aTBref and the TBForum open in my browser so that I can look up things immediately. I also look at other people's work (Tekka, Mark B's other web work, Blaty, bsag, and anything else). I look at the Cookbook, too. I am not neglecting anybody. I'm learning a new lexicon--not just an app. What seems transparently clear to anyone who takes the lexicon for granted is not clear to me.

For example: Fortunately, I was able to look up "deprecated" on google. I eventually found, more slowly ==. But not understanding the meaning of "an equality test," as opposed to "the left side is equal to-- or points to-- the right side," I wrote in my notes "don't use =  will go away soon." After a few hours of struggle, I learned the correct distinction. I can see the power of Tinderbox. It's just not an easy reach.

Mark B. I think that the Help menu is definitely more attractive and has more visuals (which are really helpful) than the pdf manual. I also like that I can download it in parts. But the advantage of a pdf with a toc and page numbers is the possibility of writing in different colors, translating the foreign lexicon into one I can grasp or writing in the examples that help me understand, using blue when I think I get something or imagine a use for something, and red when I discover a misunderstanding and write a correction. Someday maybe all that can go into TB, but for now it's on my pdf copy and small notebook that references it. And will now reference the Help Menu.

I appreciate all these resources, but most of all, I appreciate your tending to the needs of your novice users on this forum. Thanks much for that. :)    

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.