Re: [ng-spice] Docs
On Thu, Sep 02, 1999 at 01:05:53PM +0200, Manu Rouat wrote:
> Hi,
>
>
> since we have now a texinfo file for documentaion (meaning we can have dvi,
>ps,
> html output...) I wonder whether we should keep or not the old (archaic)
>help
> system that came with spice3. The only thing that would be usefull as an
>online help
> would be a 'help' command , associated to the command you wish to know about
> for instance :
>
> > help pulse
> 'pulse' defines a waveform with the syntax ...etc..
>
>
> this is the way ACS handles it. I think that this would simplify
>maintenance.
> The ideal would be to have one single doc file, that can have all kinds of
> possible output formats. Arno, do you think it is feasible?
The online documentation should be compiled into the program (as
opposed to be put in a separate file). This allows for i18n using the
gettext library. For a more extensive treatment of the subject, we
could fork an info reader or web browser and have it search for the
relevant term in the index. This is what Octave (a Matlab
replacement) does. It works quite nicely.
There are different kinds of documentation: a quick reference, a
reference manual, a users guide, a tutorial, a API description. Each
address different documentation needs for different kinds of users.
People starting with spice, seasoned users that need a concise
reference manual and programmer documentation for souls who want to
write shared library extensions.
So far, the texinfo manual mostly covers the needs of the seasoned
users. It mostly lacks a good index to be truly useful. On the other
hand, I would like to see the descriptions of the devices be put in
their respective directories. This also fits nicely into the proposed
library approach to the device simulation. The final reference
documentation can include the different parts.
It may be possible to contain the reference documentation in the
source files but it requires some automatic processing to extract it
from the sources. Programs like c2man or cweb partially address this
problem but IMHO they are not suited for extracting the kind of
documentation we're after here. Next best thing would be a
roll-your-own-documentation-extraction-utility. Any volunteers?
Let it be clear that I am all in favour of junking the old system.
--
Arno
Partial thread listing: