RE: [Aimmath-developers] AuthoringGuide

[Ken M. <mo...@pt...>]

Hi Greg and Gustav,

Let me reply to both of your messages regarding the AuthoringGuide.pdf file
at the same time.

> -----Original Message-----
> From: aim...@li...
> [mailto:aim...@li...]On Behalf Of Greg
> Gamble
> Sent: Tuesday, September 09, 2003 11:54 AM
> To: AIM developers
> Subject: Re: [Aimmath-developers] AuthoringGuide
>
>
> On Tue, 9 Sep 2003, Gustav W Delius wrote:
> > Ken,
> >
> > I really like your Authoring Guide. It would be very nice if we could
have
> > the contents of syntax.html included in that document as a first
chapter.

I had considered them to be two separate documents, with syntax.html and the
autogenerated package docs documenting the exact syntax for the AiM question
files, and the AuthoringGuide being a author's guide explaining how the
various syntax and built-in packages can be used to author questions, i.e.
syntax.html and the autogenerated docs are rigor, whereas AuthoringGuide is
exposition, tutorial, and quick reference.  However, if we want to combine
both into a single User's Manual, that might not be a bad idea.

> > Are you already working on that? Or do you want someone else to do that
(no,
> > I am not volunteering :-)).

As I said in my posting to this list of Sep 1, 2003:

----------------------
 -----Original Message-----
 From: aim...@li...
 On Behalf Of Ken Monks
 Sent: Monday, September 01, 2003 3:11 AM
 To: Aim Developers
 Subject: [Aimmath-developers] authoring tools and other mods
 :
 :
 6. AuthoringGuide.pdf (in the docs directory)

 This is a temporary rough draft of what I hope will eventually become a
 question authoring guide.  Currently it only contains a brief tutorial on
 using the Inert package, but I hope to add sections about the Random
package
 and the Rand command, and the SET, Decimal, and Number packages.  Perhaps
 others will want to eventually add sections about the Int, Diff, Trig, etc
 packages... i.e. anything that is primarily a question authoring tool.  I
 think this would be a big help for new question authors.  I often find
 myself writing a particular utility, only to find out later that it already
 exists somewhere in the AiM code.  This would be a more direct way to learn
 what tools are available.
----------------------

So far I have finished the sections in the Inert package and the Rand
command.  The next priority is the SET package (with Decimal and Number to
follow).  After that I intend to convert it to whatever format people want,
and post it more permanently.  If I convert it to html (see further
discussion below) then we could make a link to syntax.html at the top of the
document as a "first chapter", but if we also want LaTeX or pdf versions,
then we might want to add the contents of syntax.html to the Authoring Guide
as you suggest.

> I assume you are using tex to produce the pdf?

Well not exactly.  I'm using Scientific Workplace, which is a WYSIWYG front
end for LaTeX (it's really nice, IMO!).  The pdf file was produced by
printing the WYSIWYG version directly from the editor to Acrobat Distiller.
The file is saved as LaTeX, but I didn't compile the LaTeX to print it.  If
I do compile the LaTeX, I will loose all of the colors and fonts that you
see in the pdf, and it will look like a plain LaTeX document.  While I do
have a style file that makes the fonts and colors, it is a SWP style file,
not a LaTeX style file. SWP can also export the document to HTML and will do
a decent job of keeping the fonts and colors.  However, the downside is that
it produces a zillion image files for all of the included mathematics and as
usual the conversion isn't formatted quite as well.

But the bottom line is that we can have it in pretty much whatever format we
like eventually.

> > Would you share your style file?

Sure, if anyone else is using Scientific Workplace. :)  I'll also be glad to
post the html and LaTeX source as soon as I'm done.

> Dear all,
>
> While it's nice to have documentation in other formats, I think it's
> important to have a `standard' format, which up until now has been
> HTML, most of which is autogenerated by AIM via Maple. So, I'd like to
> see the Authoring Guide in HTML format.

I apologize if I wasn't clear about my intention with AuthoringGuide.pdf.
The key phrase to notice in my Sep 1, 2003 posting above is "This is a
temporary rough draft".  It was not my intent to leave the document
permanently in pdf format. As I said in the Sep 1 message "Perhaps others
will want to eventually add sections about the Int, Diff, Trig, etc
packages... i.e. anything that is primarily a question authoring tool.", and
this certainly can't be done to a pdf file.

No, what happened is that I found myself up against the beta release
deadline and am writing up documentation as fast as my little fingers can
type. It is *much* easier for me to type it in SWP than in HTML because of
the all of the mathematics I needed to include.  SWP can export to html when
I'm finished, and saves the document in LaTeX, so I knew I wasn't locking us
into any particular format by typing it in SWP, just making my life easier
while trying to finish all of that documentation ASAP.

> Also, I'd like to see the documentation for Rand with all the other
documentation.

The documentation for Rand, and Inert and all of the other minor packages I
uploaded is indeed also autogenerated and included with all of the other
documentation, in addition to being discussed in Authoring Guide.  However,
I think asking someone to learn about the Inert package by reading the
autogenerated documentation is like asking them to learn calculus by giving
them the axioms for the real numbers.  Similarly, while the autogenerated
docs for Rand() give the exact syntax, they don't explain how the recursive
nature of it can be used to define more complicated random structures, as
illustrated in the Authoring Guide. I think if you read the AuthoringGuide
and compare it with the autogenerated docs you will see what I mean.

Also, in general, I think we need an Authoring Guide.  There is SO much
autogenerated documentation, that I don't think we could expect a new AiM
author to read all of it and to realize which parts of the documentation
deal with authoring tools and which are documenting the internals of AiM.
For example, the Int, Diff, Trig, SET, Decimal, Number, Functions, and Inert
packages all deal with things that a question author might find useful for
writing questions, while most of the other packages would never be used.
Even within the packages I just mentioned there are some routines that are
internal utilities, and lots of documentation about the fields and methods
defining the classes that the question author does not need to be concerned
with.  So I think we definitly need a document that a question author can
read in order to learn about all of the built-in tools for question
authoring, and to see examples of how they can be used, all in one place
rather than them having to read through the entire autogenerated
documentation system to find out what is available, and trying to figure out
on their own how it all works.

> It doesn't hurt to have other formats available as well, but rather than
produce
> a whole lot of different pieces of documentation in a hodge-podge way,
> it should be consistent ... to do this means accepting one format as
> a base format, inventing some rules about style (largely done already
> by Neil when he created the auto-documentating tools for AIM), and
> creating tools to convert from the base format to the other formats.
> The base format could be HTML or it could be LaTeX or even XML.

It can easily be converted to HTML and easily posted as LaTeX.  I'm still
typing more documentation, but when I'm done I'll gladly post it in HTML,
LaTeX, SWP, and pdf. :)

> IMHO, if we are to go down this road, I'd like it to be LaTeX,
> which would mean defining the style and tailoring a LaTeX-to-HTML
> tool to give output that matches the existing AIM auto-documentation.
> Perhaps, Neil already has such a tool that he used to generate
> syntax.html etc.??

Sorry if I made you think there was any "road" we were going down.  The only
road I'm headed down is the "hurry up and type up all this stuff any way
possible and worry about the permanent version later" road. :)  However,
since the topic came up, I would say that it might not hurt to have a nice
AiM User's Manual that includes the Authoring Guide and the contents of
syntax.html in LaTeX and pdf in addition to the available html docs.

KEN