At 10:36 PM -0600 1/2/03, Richard D. Jackson wrote:
Spot on. Much like that layout from Web Design in a Nutshell as I was referring to earlier (I did post that didn't I?),
No I don't recall seeing it.
See below.
but with all the bits together in one place. I still prefer the layout of WDIN as it interates with written documentation well (not the automatic annotations, but the long hand description of the aims and use of some feature which usually written after the fact). Also it means there are short appendices with just the least needed to remind you of the keywords, parameters, etc.
do you have a URL for example output of WDIN?
= Web Design in a Nutshell, in cause you didn't guess!
If the sample chapter HTML page is anything to go by, I dont think the new book is quite as good as the old with respect the layout of this section; its shown better below in my typing I think.
Here's the bit I though I'd posted earlier, which ought to explain it (makes me wonder if I ought to repost the full post - it had a few other bits in it too) :
Since the list is generated automatically, this should be rather easy to do. But would it help, or be more confusing?
Hmm. Both, but in my ideal world (!) I'd lay out the docs. in a different way. To me the best indexing/reference scheme I have seen is in 'Web Design in a Nutshell' (O'Reilly). I wish O'Reilly would use it in their other books. The index (or appendix) has the keywords in alphabetical order, referring you to an appendix with brief synopses of the keywords in alphabetical order. These, in turn, refer you to a complete synopsis at the head of a chapter. If you still can't remember how to use the thing, you're conveniently at the start of the chapter that covers that subject area needed to (re)learn it.
The beauty of this is that it can be read either front-to-back or as a reference via the index/appendices without either disrupting the use of the other.
For example, <frameset> in the index, points to p473, which contains
<frameset> Chapter 11, page 207 ------------------------------------------------- Description: Frameset Attributes: border bordercolour cols frameborder framespacing ...
Page 207 has the full synopsis, with standards support and short descriptions of the keyword's functions, eg:
<frameset> NN: 2,3,4 - MSIE: 3,4,5 - HTML 4 - WebTV - Opera3 ------------------------------------------------------------------------ <frameset> ... </frameset>
Defines a collection of frames or other framesets
Attributes
border=number Sets frame border thickness (in pixels) ... ...
If you're _still_ stuck, you read the chapter that follows.
There is a nice hierarchy that you traverse, stopping when you've reached the level you need. If you're learning, you read from the front.
This looks like a lot of work, but if done from HeaderDoc or the like, it might be possible to automate much of this straight from descriptions in the source code.
It shouldn't be too hard to make the HTML docs like this with links for the page nos., or likewise links in PDFs. I have to admit I have a vested interest in this layout, as its its precisely how I'd like to publish my API docs...
Besides, we could aim to write our own O'Reilly Nutshell book :-) JK! (And I really mean JK!)
But this style is good for an on-line doc.
FWIW, I'm interested in that particular layout as its how I intend to doc my APIs.
Grant
It is allso the way I want to do mine as well.
By this, I meant the way the WDIN book is laid out. Which, since you haven't seen it, can't be what you're referring to...! So, err, what _are_ you referring to?!
But I think for a first pass I will take a harder look at what frank wants as it is not nearly as complicated as what we want.
I get that impression too.
But one of the things I really need to do is look over what texinfo can or can'nt do. Because I would really like my online doc's and printed docs to have a simular layout if possible.
Personally I'm going to leave texinfo out of mine, but that has to do with the fact that I want it to tie in with my little computer language project and I don't want that too dependent on other things as if it even come to completion it'll have to stand on its own two little feet ;-)
Grant