About file formats (was Re: [Axiom-developer] First (quick & dirty) port of Axiom to gcl-2.5.2 and powerpc architecture)

[David MENTRE]

Hello tim, ;)

root <address@hidden> writes:

> (C) FILE FORMATS 
> Pamphlet files go to dvi files. That's sort of ok as dvi files work
> everywhere. However, we need to plan in the long term and think about
> a way to automatically organize the information in pamphlet files.
> I've been thinking about creating a meta-pamphlet file in each
> directory (possibly automatically created by make) from <<meta>>=
> tags in the pamphlet files. This would allow pamphlet file writers
> to specify how the available information should be used. So the
> make walks across all of the pamphlet files, extracts <<meta>> 
> chunks, munches them into some organized form, creates a latex 
> table of contents, and generates a new dvi file.

Why not use noweb facility to standardize some predefined noweb chunks,
like:

<<user documentation>>=

<<Makefile>>=

<<programmer documentation>>=



> Several issues arise including things like the fact that dvi files
> don't support hyperlinks so some sort of a viewer needs to exist.

DVI files does support hyperlinks. Just include the 'hyperref' (or
'hyperef'?) package at the beginning of the latex file.

> Ideally this would be some standard viewer as we'd have less code
> to maintain. 

Why not use the PDF file format. Substitute pdflatex instead of latex
and bingo, you have a pdf output (of course, you must have installed
necessary packages from your linux distro).

And, as a bonus, using noweb and hyperref, you have cross references
between code chunks. I tested it on C code with noweb facilites to index
C code. Of course, we should do that for Axiom programming language.

> Ultimately we need to think out how the pamphlet, booklet, and 
> other documentation/usage/FAQ/maint information is going to be
> structured and viewed.

Yes. For example, should we produce one big book (like Knuth TeX Book)
or several small books?

But probably usage will tell us some insights. Why not choose an easy
approach and correct it if it is the wrong path?


Best regards,
d.
-- 
 address@hidden