RE: 5x5 documentation

[Vincent Belaïche]

Hello,


I removed Manuel from the recipient because I had put them in the loop only for the math aspects...


Concerning your suggestion, this is something that I had often thought about that it would be good if docstrings would allow better interaction with manuals, like be written with some markup to allow other format (like some Org mode like, or some simplified texinfo). 


It would be good if a docstring could point at some anchor in a manual. I had started to think about that because in Calc there is no docstrings at all, but rather some function that scans the manual for the function description. Unfortunately this function first uses the language in which the manual is written, which is not good programming practice to make any algorithm locale-dependent, and second this function had a number of bugs which were corrected over time, which shows that this method is hard to tune. 


It would be better to have some markup to say "hey !  go the the point that correspond to index entry XXX where you find that index in this index info node", and XXX is the function/variable/etc... to document and that has some index entry.


That would also allow to make function/variable documentation internationalized.


Anyhow, a simple-to-do thing would be to place this manual in some place, like similar to that of sed:


http://gnu.april.org/software/sed/manual/


And then put an url to this page in some docstring or in the emacs manual info node about games.


   Vincent.

> From: address@hidden
> To: address@hidden
> Subject: Re: 5x5 documentation
> Date: Mon, 20 Jun 2011 23:19:09 -0400
> CC: address@hidden; address@hidden; address@hidden; address@hidden; address@hidden
>
> > Somebody from this forum asked for documentation of the algorithm which
> > I used. So I wrote a comprehensive documentation of 5x5. Actually the
> > primary objective was just to describe the algorithm, but it ended in
> > describing the whole thing.
>
> Thanks. I don't think we'll want to include a separate Texinfo manual
> for that with Emacs, tho. We could include a version of that doc as
> a comment in 5x5.el (could be marked up (maybe even with Texinfo markup)
> and come with a command that would extract the text from the comment and
> pass it to some tool for rendering, if you want to get fancy).
>
>
> Stefan
>