On 26 Jan, Carilda Thomas wrote:
> What I wanted to do is:
> (and I would be working directly from source for the info to use here.)
> 1. create manual pages for the current 1.2.5 release for all functions
> implemented:
Now, these two efforts won't in any way be exclusive
of each other. The idea in gathering material for
documentation writers is in creating a repository
of information that people writing usage documentation
(tutorials, installation instructions, etc.) can use.
Of course, besides these, good reference material
on the functions will be needed.
> If there is a function page already, I will use it, or possibly correct any
> mistakes I find on it (spelling, typos, inaccuracies, whatever).
There is the function reference Jukka, Jean-Pierre,
Emile and a couple of others have been working on.
I think it is quite up to date with those functions
that it has material on, but many descriptions are
still missing, and the existing ones could be
improved with more usage examples and other things.
The function reference is part of the Midgard
manual, and can be found from
http://www.midgard-project.org/manual/funcref.html
The actual SGML sources are in the doc/functions
directory of Midgard's CVS repository.
> Then, in the UNIX man page style, we can have sections for BUGS, SEE ALSO,
> whatever.
This sounds good, the man page format would certainly
be useful. But if we can manage it so that the same
material can also be available in HTML format, then
that would be even better.
<snip>
> Probably I will go to TUG and join and buy their CD-ROM. (Hang head in geek shame
> for having to install binaries....)
We give everybody with CVS write access also an account
on our project server, and that could also be used for
this. However, it is very poor on resources (an aging
P100 with only 1.5GB of disk space) and far away here in
Finland so it probably wouldn't be useful for these
purposes.
> Meantime, should I start sending pages in, (I guess just plain text format, but
> I think that is going to create a lot of work for y'all when you could be doing
> more constructive things) or is there a format (with containers) that exists to
> minimize your all's work when actually installing this?
We haven't yet thought of what format the man pages
should be in, so I guess plain text will be ok. After
all, it is far more important to get the material
written than have to it in a specific format.
> cat
>
> P.S. If we can get this working, I can start (Real Soon Now (TM Jerry Pournelle))
> to document the functions for 2.0 -- hey -- documents before code? What a radical
> idea........ If we got that in front of everyone, it would be a very public API.
...And that would probably also help if people are to
write bindings to other languages, as then they could
see how the functions were meant to be used instead of
just how they look in the sources.
And documentation before code, an interesting concept.
I think I like the idea - as long as the actual code
also gets written. :-)
/Bergie
--
-- Henri Bergius -- +358 40 525 1334 -- [EMAIL PROTECTED] --
http://www.iki.fi/Henri.Bergius
--
This is The Midgard Project's mailing list. For more information,
please visit the project's web site at http://www.midgard-project.org
To unsubscribe the list, send an empty email message to address
[EMAIL PROTECTED]
