Robert Dodier writes:
>Hi Vadim,
>
>Thanks for your recent work on the Maxima documentation.
>It really needs a lot of work! That said, I guess I recommend
>an incremental strategy rather than major changes all at once.
>I'm inclined to keep the everything in a workable state
>all the time.
>
>
>
Actually I don't insist on any radical changes especially ones
which going to break documentation.
>I agree that the organization of functions into .texi files
>is somewhat haphazard. However, since the organization of
>functions by file has little effect on the "describe" output,
>I would steer away from large-scale changes to address
>organization. There are some "Definitions for ..." @nodes
>in the .texi files, which comprise a large number of functions;
>I guess some functions should be moved so that each function
>falls under an appropriate "Definitions for..." heading.
>
>
>
I feel that sooner or later documentation needs a major reorganization
(Don't forget that docs - it is not only "describe" but hard copy and
html for browsing). Modern docs sectioning is far from being optimal.
But I agree right now it is not our primary concern.
>I guess I would recommend against moving descriptions of
>broken functions, and broken descriptions of working functions,
>into a special directory. I would rather leave the descriptions
>and file bug reports as needed. I would claim that even the
>out-of-date documentation is useful.
>
>
It depends. You already deleted some clearly outdated definitions.
Right? Of course any deletion must be done very carefully -
only clearly irrelevant pieces.
>Moving None.texi and xrefs.texi into the archive directory
>makes sense to me.
>
>
OK
>I share your concern for the documentation -- that's
>why I'm working on it -- but I guess I don't feel the same
>urgency; some parts have been out of date for many years,
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>so it can't be too important to fix them.
>
>
>
Well, this is sad ...
>Incidentally, my own bias is to revise the parts of the
>documentation which are most needed by new users.
>This (I'm guessing) is stuff like saving & loading files,
>using the debugger, other command line stuff, etc.
>
>
>
Yes, this is right approach and thank you very much for doing this.
My idea is was to make Maxima documentation in sync with
Maxima reality right now with short period of time.
This is why I suggested to move nonworking
parts into some temporary storage (not delete it permanently).
One of the problem is docs translation to other Languages.
There are people who volunteer to help (Spanish, Russian ...).
But what these people should do with these notorious "nonworking"
parts. Translate them and later re-do the work when these
parts will be finally fixed? I really don't know.
But this is just idea ...
>regards,
>Robert Dodier
>
>
--
Vadim V. Zhytnikov
<vvzhy@mail.ru>
<vvzhy@netorn.ru>