Re: Creating a Cocoa Help Book
Re: Creating a Cocoa Help Book
- Subject: Re: Creating a Cocoa Help Book
- From: Matt Neuburg <email@hidden>
- Date: Mon, 02 May 2005 10:09:28 -0700
On Mon, 2 May 2005 17:53:16 +0200, Jose Antonio Ortega <email@hidden>
said:
>
>On May 2, 2005, at 00:58, M. Uli Kusterer wrote:
>
>> Hi,
>>
>> just thought I'd add a (late) alternative to this thread: I just
>> cobbled together a little shell scripting that allows using PHP to
>> write your help book. I'm simply using "find" to loop over all
>> the .php files and then call upon the PHP command line tool to
>> generate HTML files from that in a Shell Script Build Phase.
>>
>> [...]
>
>Hi,
>
>Interesting idea! In fact I am thinking of doing something similar,
>only with other scripting language (I am afraid I don't like PHP)...
>I'll keep you posted.
>
>Thanks for sharing. And thanks also to Todd for his previous answer
>to my initial query. FWIW, I think I won't write HTML directly;
>before this last post by Uli, I was convinced to use LaTeX, but maybe
>I'll use some scripting language + HTML generation libs. I'm not sure
>which one yet, for I'd like to also generate the PDF manual from the
>same sources.
I missed the earlier part of this thread. I'm sorry to repeat myself, but I
would suggest you read John Gruber's review of my help for Affrus, and my
article on how I wrote it:
<http://daringfireball.net/2005/02/apps_of_the_year_2004>
<http://www.macdevcenter.com/pub/a/mac/2004/03/30/online_help.html>
The thing to notice here is that John praises the online help because it is
"hyperlinked out the wazoo" (or words to that effect). That's crucial. You
are not going to write good online help unless it is very, very, very, very
easy to make hyperlinks - because it if isn't easy, you won't make them, and
if you don't make them, your help will not be as good as it should be (in
fact, it will probably suck). So I recommend using, as a bottom line, a
milieu where that is true. It doesn't have to be Tinderbox, obviously, and
I'd never claim that Tinderbox was perfect (in my article I point out that
we had to run everything through a Perl script to make up for Tinderbox's
shortcomings), but it does let you hyperlink like mad, and it generates HTML
for you, including (most importantly) navigational links. And we did get it
to work in this particular case.
If I had not used Tinderbox, I would probably have opted for Frontier, which
would have created much better HTML much more easily (and is now available
in a free open source version); but making links is a lot more work in
Frontier; every page has a unique identifier, and you have to know what it
is and type it in. In Tinderbox, you just select the phrase you want to link
from and drag to the "page" you want to link to. That's so easy that you do
it unhesitatingly, and it is this unhesitating willingness to link that
makes this help book what it is. This is a case where the user interface of
the milieu you're working in really matters.
This does not solve the PDF problem. We had this problem too, and in the end
we just gave up. In theory it should be possible to munge Tinderbox's XML
(using XSLT or whatever) to do anything whatever, including making a PDF,
but in our case this ultimately remained just a theory. I'm afraid that if I
were asked to suggest a milieu where it was a easy to make really good PDFs,
plus HTML/XML, I'd suggest FrameMaker! m.
--
matt neuburg, phd = email@hidden, <http://www.tidbits.com/matt/>
A fool + a tool + an autorelease pool = cool!
AppleScript: the Definitive Guide
<http://www.amazon.com/exec/obidos/ASIN/0596005571/somethingsbymatt>
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden