[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: gEDA-dev: What should be included in the dist file?
On Wed, 2006-08-16 at 18:10 -0400, al davis wrote:
> I got only one response on the gnucap-devel list, and it really
> is a general question, so trying it here...
>
>
> Considering a recent comment about pdf files, I ask...
>
> What should be included in the dist file?
>
> Obviously all source, including the manual.
>
> What about some things that are not source?
OK. I'm probably going to ruffle a few feathers, and start a flame-war,
but here is a much different option. Don't include the documentation
with the distribution.
The reason. The gEDA wiki holds the repository for the latest
documentation. If a user wants the latest documentation, the user should
be encouraged to get that documentation from the gEDA wiki. If a
developer (or heavens forbid a user) wants to update the documentation,
they can simply modify the content in the wiki.
Document authors should be aware that they can, after logging into the
wiki, subscribe to changes made on any particular page (e.g., a
wiki-page they authored). In this manner, document authors may follow
changes made by others (an e-mail is sent by the wiki-engine when page
changes are made).
I've provided Ales with a pavuk script, which will convert the wiki
pages to XHTML. These XHTML pages are what is likely to be placed in the
geda/gaf portion of the documentation (at least).
Ales is still playing with this (trying different look-and-feel
aspects), but I expect that shortly after the next gEDA Tool Suite
CD-ROM release the gEDA wiki Documentation page will be modified so that
the XHTML will be dynamically generated whenever the link is pressed
(i.e., pavuk is automatically invoked so the wiki-page is converted to
XHTML and delivered to the browser). It won't happen immediately, as it
requires software to be installed on the seul.org server, but there
should be time to do this after the CD-ROM is created.
For example (for those concerned about how the wiki-page translates into
an HTML-page), I just converted the "gEDA/gaf Symbol Creation Document
on the wiki Documentation page to an HTML page and placed it on my
web-site at:
http://www.offramp.com/temp/geda_scg.html
As a minimum, if the application includes a static copy of its
documentation on the CD-ROM install image, it should indicate that the
latest documentation is on the gEDA wiki. This should be made clear in
the application's documentation.
Anyone needing help converting existing documentation to the gEDA wiki
format may contact me. I am more than willing to help. Most of the
documentation from the last gEDA Suite CD-ROM has already been
converted.
Flame away...
Dave Hart...
>
> Documentation:
>
> 1. HTML files?
>
> 2. DVI files?
>
> 3. PDF files?
>
> 4. PS files?
>
> My comment: People should be able to read the docs doing
> anything else. Requiring the tools to compile finished
> documentation adds another dependency.
>
> Does anyone use dvi files as anything but an intermediate
> format? (either as a starting point or final product)
>
> Should there be another file, distributed next to the source
> one, with finished docs?
>
> Should several options be offered:
> 1. complete (including processed docs)
> 2. source only
> 3. processed docs
> 4. testing files
> --- this is 4 files offered for download.
>
> One common mistake I see is to give only short names for the
> files, so I am not sure what I need. So, I download them all
> only to discover duplication.
>
>
> What about regression test files? (the test subdir).
>
> Does anyone actually use them?
> Does anyone else know how to interpret the results?
>
> Comment: With floating point, often you don't get an exact
> match. I have seen it different between Intel and AMD
> processors.
>
> I looked at the GNU standards to see if there is a way they
> recommend. I didn't see anything.
>
> What about generated "source" files? These are files in C or
> whatever, that look like source, but are actually generated.
> My experience is that to include them tricks people into
> thinking they are source, causing more problems, but may allow
> them to build when a translation program (m4, awk,
> gnucap-modelgen, autoconf) is not available.
>
>
>
> I solicit opinions in this. I have no bias toward any
> particular way of doing it.
>
>
>
> _______________________________________________
> geda-dev mailing list
> geda-dev@moria.seul.org
> http://www.seul.org/cgi-bin/mailman/listinfo/geda-dev
_______________________________________________
geda-dev mailing list
geda-dev@moria.seul.org
http://www.seul.org/cgi-bin/mailman/listinfo/geda-dev