Hi.
I'm using a typsetting application called DECdocument.
This is an application that originated from Digital
Equipment Corp (DEC, VAX and VMS if that rings a bell).

When compiling a document, one selects a "style", in
this case I selected "SOFTWARE.REFERENCE".

DECdocument is a "text markup" tool, actualy it is
based on SDML (Structured Document Markup Language)
which is, in a way, very much like HTML, but with
added "tags" for such things as "chapters" and other
document related things.

I can agree on that the left margin for running text
is a bit wide, but that was the format selected when the
selected style was defined.

I'm not going to digg into the inner works of DECdoc to
change this. Print double sided and save a couple of
sheets ! :-)

I'm not realy sure what you mean by "shortcuts" and
"navigation pane". Is that the "link" that you can put
into PDF files ? Problem is, my tool (DECdoc) outputs
raw Postscript, and DECdoc don't have any tags to include
this kind of information. It *could* be added later
using "Acrobat Exchange" (the full version), but then
I'm stuck with manual editing of the document which
I'd like to avoid.

As for adding "gothas", "hints" and other stuf. I'd like
to keep the main chapters of the document as close as
possible to Olins texts to make it easier to update. Note
that the SDML file for the STD_INS macro part is generated
automaticly directly from the ASPIC file by a script with
no manual editing. I would like to keep it that way. (The
script need a bit of tweeking, the formatting of the
macro descriptions is lost now...)

I'd like to look at the current document content as
a "reference", and then add "gothas" and "hints"
to section separated from Olins original texts in a
chapter of it's own. That way it will be easier to
maintain.

Now, with that said, I'll take a look at the others
document "styles" in DECdoc. There is one called
"SOFTWARE.POCKET_REFERENCE" that looks to be more
compact. Maybe it could be used for a condensed
"ref-card" ? I'll check...

Also note that the currect document was produced
during 3-4 evening hours, I *do* plan to both
add more and fix some formatting issues.

Well, did that answer your questions ?

And, finaly, this is unpayed hobby stuff :-)

Jan-Erik.



Alan B. Pearce wrote :

>I also downloaded it and had a browse. It looks good, apart from the little
>bits that John noted. Much better than the Word document that I made for
>myself from the STD.INS.ASPIC file so I could find my way around the macros
>while writing code.
>
>The only comment I would make is why so much white space beside the text?
>With only half the page width used it may make it OK to have as an overlay
>on a computer screen, but this sort of documentation I prefer to print off
>and have in a folder on the desk, and the way it is formatted nearly doubles
>the number of pages.
>
>You may want to have some shortcuts available in the navigation pane, to get
>to the macro descriptions. This would make it really useful having around as
>an overlay while programming. Did not read the macro descriptions carefully
>to see if these were already there, but do put in some details of "gotchas",
>(like the FIFO macros using the FSR) or processor dependencies.
>
>All up a very good effort to bring all the info into one place. I do like
>it.

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.