RE: [Aimmath-developers] AuthoringGuide

[Greg G. <gr...@ma...>]

On Tue, 9 Sep 2003, Ken Monks wrote:
GWD> 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.

What can I say ... I'm not in favour of using Scientific Workplace. My 
feeling is that the base format should be plain text, and something easily
transformed into the wanted formats (.pdf, .html, ...) from that base 
format by anyone of us. Now, if you were able to provide a LaTeX 
documentclass. Then that could go into an etc/ directory of the CVS 
repository, and we would all be able to add to the base format file
and be able to reproduce the wanted formats (given that a translation
function, probably written in Maple because that's accessible to all).

What I don't like about Scientific Workplace is the sort of LaTeX it
produces; because its WYSIWYG, centring is done by a series of \  
(explicit space commands) rather than by using the appropriate centring 
environments, i.e. markup tends to be done explicitly rather than 
logically.  

> 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.

Look ... I don't want to be a stick-in-the-mud. I agree with you. It's 
much more important to get the documentation `out there' ... but please
make a plain text version available. Maybe, when I've got time I can put
together a tool or tools to make the form consistent. I don't know about
you, but I find documentation *much* easier to read if it's in a 
consistent form, and much more difficult when the style keeps changing.

> > 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.

I agree with all this too. I have produced quite a lot of documentation 
myself. What I find is, most users go straight to the examples or 
templates ... only serious users read the manual, and most of these only
become serious users after playing with the examples first. Hence why
I thought an examples/ directory ought to be there with, eventually,
examples of all of the features of AIM.
 
> 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.

I agree absolutely.

> > 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. :)

My reservation is that we should all be able to regenerate the 
documentation from a simple plain text base format. If you can use
Scientific Workplace in such a way that generates a simple plain text base 
format, then that's fine with me.
 
> > 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. :)

I'm ok with that ... as you say, we can make things more consistent later,
and having a few example docs helps in formulating the consistent style
(and the `rules' I spoke of, previously) anyway.

> 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.

Yes, I agree with that.
 
  Regards,
  Greg