Re: one page per method or function

[Andrey Novoseltsev]

On Dec 16, 9:45 am, Minh Nguyen <nguyenmi...@gmail.com> wrote:
> Hi folks,
>
> I have converted the whole reference manual use one page per method or
> function. The resulting HTML version of the reference manual is up [1]
> at Google code for your viewing pleasure. The script that I used in
> the conversion process is up at bitbucket [2], from where you should
> also find a patch to sage-main that would allow you to build the
> reference manual with one page per method/function.
>
> I can see several problems with merging the above changes to the Sage
> library. If you merge the above patch, building the HTML version of
> the reference manual would take over 100 minutes, where previously it
> took about 30 minutes. This is really unacceptable. Another problem is
> that the log of the build shows 967 warnings, many of which I have no
> idea how to resolve.
>
> While having one page per method or function is really a good idea, it
> has created further problems. A reasonable alternative is to leave the
> documentation building process intact. It already takes a lot of time
> to build Sage and the whole standard documentation. The online [3]
> reference manual that is accessible from the Sage website would be
> generated to use one page per method/function. In all, no patches will
> be proposed for merging into sage-main and the online reference manual
> would be generated to use one page per method/function. I'm sorry for
> raising so much fuss about this one-page-per-method-function issue.
>
> [1]http://mvngu.googlecode.com/hg/onepage/index.html
>
> [2]https://bitbucket.org/mvngu/oppmof/src
>
> [3]http://www.sagemath.org/doc/reference/index.html
>
> --
> Regards
> Minh Van Nguyen

Hello,

I think that one-page-per-method style is way better than the current
one, since it allows users to see quickly what methods are available
for a class and there is no problem "loosing your place" when you
scroll up and down through the documentation. So it would be nice if
local documentation was also building like this.

As for build time, why not drop building documentation at all and let
users choose whether to build it later and in what form? I used
patches from http://trac.sagemath.org/sage_trac/ticket/9128 for
several month and every time after upgrade I had to rebuild the whole
documentation after pushing them anyway. Although this is not a
typical situation, of course...

Thank you,
Andrey

[Robert Bradshaw]

+1. It takes longer to build the documentation than the library itself
(especially if you're using parallelisation). One of my pet peeves is
that the documentation tries to rebuild itself on every clone--it use
to take a matter of seconds to clone, now it's so painful I always end
up killing it.

- Robert

[Nathann Cohen]

>> As for build time, why not drop building documentation at all and let
>> users choose whether to build it later and in what form? I used
>> patches from http://trac.sagemath.org/sage_trac/ticket/9128 for
>> several month and every time after upgrade I had to rebuild the whole
>> documentation after pushing them anyway. Although this is not a
>> typical situation, of course...

+1 too. Plus the 1-page-per-function documentation Minh wrote is to me
much much better than what we have now, and having it only available
on internet makes it harder to work with : not very easy to deal with
two forms at the same time, and to write patches affecting how the
online version appears.

Nathann

[Kwankyu Lee]

Hi,

I love the reference manual in the new format. For building time
problem, users may be given several choices, one of which might be
just to download the built documentation from the web.


Kwankyu

[Kwankyu Lee]

Hi,

I like the new approach. In the same vein, the Contents page may be
restructured such that it lists only chapter titles, and each chaper
has its own contents page. The current Contents page is too long to
scroll down to reach what I want.


Kwankyu