Re: [Axiom-developer] build-improvements and latex

[Ralf Hemmecke]

On 11/08/2006 03:39 AM, Gabriel Dos Reis wrote:
> Ralf Hemmecke <address@hidden> writes:
>
> | >> Underscores would be no problem at all if filenames where | >> 
> properly tagged. Note that there is a latex package called url | >> 
> (/usr/share/texmf/tex/latex/misc/url.sty) which provides a \path | >>
>  command. Together with hyperref one can turn that also into | >> 
> hyperlinks. | | > I like this idea but I think it might need more 
> thought. How do | > we want to present this large collection of Axiom
>  documentation | > files to a user? How will they navigate? How will
>  this interact, | > or will it interact with hyperdoc? Will they be 
> searchable? What | > is better, dvi or pdf? Etc. | | I have a simple
>  suggestion. Forget the Axiom user for a moment. First | we need to 
> have good documentation for developers. A user probably
>
> I care a lot about users.  I have no chance of attracting a developer
>  if I cannot first get him as a user.

Don't take me too seriously. What I meant was that we cannot do
everything in one stroke. Of course, I care about documentation for the
end user. All of the Axiom source code should become documentation for
an end user. An end user shoul actually just find his/her way quickly to
the section of the documentation in which he/she is interested. But, in
fact, even the documentation for developers should be written in a form
that makes it easy for "users of axiom" to become "developers of axiom".
So, in fact, I don't actually distinguish too much between developer and
end user. It's just that they will read different parts.

What I care about is that the overall documentation method should be in
some sense simple. And currently we have the Axiom-book for end-users
but we have a mess for developers.

I hope that makes my intentions a bit clearer.

> I very much like hyperlinks pointing to sections in other files. I 
> really disliuke duplicating documentation for no good reasons. But, I
> don't know what ALLPROSE looks like in practice (sorry, I cannot do
> everything...)

Understood.

For a 30 seconds impression click on

http://www.hemmecke.de/aldor/allprose/

Maybe that gives you a feeling of what I would like to see also for
axiom. (.pdf and .dvi basically look the same.)
And this is *not* just one .nw file (or .pamphlet if you like). That are
many. So in fact, it isn't really a problem to have file.c.pamphlet and
file.h.pamphlet separate, since the workflow would be: Read the .dvi and
if you find something that you want to edit, click there and suddenly
your editor opens the right file. In some sense that is like Tim's idea
of having a huge .pamphlet file, only that I have not. Only the
generated (more human readable) format is one file. The actual sources
are organised so that the build process gets simple.
Also note that all newer dvi viewers allow to search inside .dvi files. 
You can forget about grep.

Ralf