Re: [seul-edu] Our math discussion - Docs

[lp <prevettl@cochise.cc.az.us>]

Ray Olszewski wrote:
 
> I guess I'm not clear, then, on the scope of the comtemplated project. If it
> is primarily a description of available resources ... the online equivalent
> of an annotated bibliography ... I suspect straight text would serve just
> fine. If it is more akin to an actual math text, we would, naturally, need
> the online (and hard-copy, for, say, Postscript) equivalent of sophisticated
> typesetting. So which is it?

It's somewhere in between an annotated bibliography and a math text, I
think.
Something with more content than a list of links but small enough so
that you
could get the gist of it over an evening. Most of the content will
require
nothing more than text. But I would like to include some specific labs
that might contain math expressions, specific keystokes, maybe even some
graphs.
If someone wanted to contribute to one of those kinds of labs, they
might
find themselves trying to communicate a phrase like

"... what is the difference between the graph of 1/sqr(x + 1)
     and 1/sqrt(x - 1) .. " or some such thing.
 
That's ok, but I think it would look nicer and be easier to read if it
was rendered when it appeared on the web. I wasn't expecting that
everyone 
would submit latex documents or anything like that. (See which.) If
someone 
contributed a phrase like the above to a mailing list or the WIMS
message 
board, then I would know what they meant and could easily convert the
text 
to markup using latex or html and gifs for working drafts.

> In weighing the tradeoffs, we might want to consider the extent to which
> DocBook and similar formats, which demand that content authors double as
> typesetters, serve as barriers to partitipation. On another list, about 6
> weeks ago, I was involved in the very active, enthusiastic start of a
> substantial documentation project. After I and one co-author has written our
> (fairly substantial) parts of a first draft, the discussion turned to use of
> LinuxDoc or DocBook, switching from ordinary text editors to Xemacs of LyX,
> management of the document in CVS, and related procedural stuff. Substantive
> work ground to a halt, and it's never really recovered.
 
Yes, I gulped when I took a look at the sgml templates for Docbook. But 
if Bill can handle the Docbook markup for the text, and I can figure out
how
to do the markup for the simple math phrases - then I don't think it
will bog things down. 

> My own thoughts here come mainly from my own experience, which is
> basically a dislike of trying to mix writing and typesetting, plus seeing
> "modern" Linux typesetting tools as extraordinarily primitive compared to
> what (say) Pagemaker on a Mac could do a decade ago. I want to *write*
> documents, not *program* them.

There are raging controversies going on about this very issue. Math
educators should know about them. I wanted to have a section in the 
teacher guide called "Communicating Mathemematics" (or something to 
that effect) where we could get into these issues - where people
feel it is appropriate to use WYSIWYG markup and where the text 
markup is appropriate.

> But that's just me ... I'd really like a better sense of why others are
> (seemingly) reluctant to take on significant documentation projects. I
> already know (and now you do too) why *I* am reluctant to do so.

For the development process, this is what I am thinking of: 

1. People can contribute content to a mailing list or the WIMS message 
board or whatever, using text or links to web documents. (It might be 
interesting to have a wide variety of submissions in a wide variety of 
formats, what ever people are comfortable with. People could include 
comments about what document format or software tool they like and why.)

2. It would be my task to take all the submitted documents, organize
them and somehow get them up on the web as 'working drafts' in rendered 
form so that people can see what the content might look like in final 
form. This will probably not be Docbook markup - just something that 
will look like the final Docbook rendering. This was the stage of the
development process that I was thinking I might use latex and
latex2html.
(In the worst case it would be just html and gifs.) Contributors can 
read the working drafts, get new ideas, suggest changes, check the 
math (there's no spell checkers for math, guys), etc. 

3.Once everyone thinks we've got some closure on a useful document,
I'll send the text (along with the Docbook rendering for the math,
I hope) to Bill who can put it into Docbook format.

 
L. Prevett
Mathematics Instructor
Cochise College, Sierra Vista, AZ
prevettl@cochise.cc.az.us