This is the mail archive of the ecos-discuss@sources.redhat.com mailing list for the eCos project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Accessing config parameters in define_proc code


>>>>> "Andrew" == Andrew Lunn <andrew.lunn@ascom.ch> writes:

    Andrew> I was under the silly impression that all documentation
    Andrew> was under ecos/doc/sgml. Well, i know parts of the main
    Andrew> manual are inside side individual target packages, but the
    Andrew> makefiles are under this branch of the tree.

    Andrew> Iztok does not have the Components writers guide on this
    Andrew> web site either......

    Andrew> Humm, just ran a find . -name "*.sgml"

    Andrew> There are a few documents file this. I think this is a
    Andrew> problem. Unless you go looking, you just don't know these
    Andrew> documentation exists. It would be better if there was one
    Andrew> central place you can make them from and an install
    Andrew> process that puts the resulting html or pdf into one tree.

    Andrew> Any suggestions how to implement this?

This is going to take a little while to explain - it involves over
five years of history. Also, not everybody agrees with all of my ideas
on this issue (yet).

There are two main forms of documentation. There is reference
documentation, for example descriptions of every function in the
kernel API. There is also generic documentation, for example the
Getting Started Guide and the Component Writer's Guide.

By design eCos is a component architecture. Amongst other things that
means that it consists of a number of packages: self-contained bodies
of code which interact with other packages only through public
interfaces and via CDL constraints. It is possible to install new
packages, remove them, upgrade them, etc. Reference documentation is
associated with a package, so if you install say a third party package
into your repository you should automatically get the documentation
for that package.

Most Linux systems are also package-based, but take a different
approach in terms of file system layout. For example the gcc rpm
installs some files in /usr/bin, others in /usr/lib, and documentation
goes into /usr/share/doc and /usr/share/info. This is largely for
historical reasons. Windows applications usually take a different
approach, with most files going into a new subdirectory of
c:\Program Files. The eCos design did not have to worry very
much about history, so each package lives in its own directory within
the eCos repository. The documentation for that package should live in
a "doc" subdirectory, not in a central location like /usr/share/doc.
When you install a new package you also get its doc subdirectory.

Given per-package reference documentation, what format should be used?
One option is Unix man pages, but that is of little use to Windows
users and the standard man command expects centralized man pages
rather than ones distributed all over a repository. Instead the design
specified html as the main format, i.e. each package should come with
a number of html files. Now, html is fine for viewing but not so good
for maintaining documentation - it operates at too low a level. Hence
most packages would actually have a DocBook SGML file containing the
documentation source, plus generated html files. It is debatable
whether the generated files should be checked into CVS or generated
on the fly when preparing a package for distribution. On the whole I
prefer the former. They cannot be generated during installation, the
required tools may not be available.

So how does a user access per-package documentation? When using the
GUI tool there are no problems, the GUI tool can know about the
repository layout and find per-package documentation. However not
everybody uses the GUI tool, so you also want some sort of toplevel
index.html file. That gets updated by the admin tool whenever packages
are added or removed, in much the same way as the toplevel ecos.db
database gets updated (remember, we are still talking about the system
design here - both index.html and ecos.db are generated, never edited
by hand).

There will be a small number of generic documents, e.g. the Getting
Started Guide, which do not belong with a package. Instead those live
in a doc directory parallel to the packages. There are only a few of
them, the admin tool can have some built-in knowledge.

PDF's are more difficult. There is no problem with the generic
documents. You can also generate a per-package PDF with no
difficulties. If you want some sort of reference manual that
incorporates all the per-package documentation then you need some
scripting to find the appropriate sgml files and do the equivalent of
#include's. Also, you need to figure out what package documentation to
include and in what order. For example, should the reference manual
really include the documentation for every single HAL package and
device driver? What about packages provided by a third party and
installed via EPK's? Lots of little details to work out.

Much of this was in the original design documents, but did not make it
into the initial implementation. The reference documentation was
centralized, not distributed on a per-package basis. Without a
convention that every package has a doc subdirectory, many packages -
especially HAL's and device drivers - ended up with little or no
documentation. For example, given an architectural HAL it would be
good to have some documentation explaining how the HAL specification
was mapped on to that architecture, the division of labour between
architectural, variant and platform HAL's, etc. From a maintenance
perspective it is better to keep the documentation close to the code.
You can imagine an emacs mode which, whenever you update a ChangeLog,
also loads in the package's documentation source file in case you want
to update that as well...

Worse, the centralized documentation was not maintained in DocBook
format. Instead it was encrypted in a proprietary format, and could
only be edited using some GUI tool which the engineers did not have
ready access to. A perfect recipe for bitrot.

Things kept going like that for some years with plenty of new packages
being added, especially ports and device drivers, but the
documentation did not really keep up. One of the goals for the 2.0
release was to correct some of these problems (not everything), and
actually implement the relevant parts of the original design. The
encrypted documentation was converted into DocBook, and some bits like
the kernel docs received a major overhaul. Other documentation still
needs a similar overhaul, and there are lots of packages with no
documentation at all. Even generic packages like the eCos
infrastructure. Work is also needed on the administration tool side to
generate index.html - right now it does not do anything special for
documentation. And a sensible reimplementation of the admin tool
requires some other infrastructure that was never implemented...

It will take time. Meanwhile various ad hoc solutions may help, but
should not make it significantly more difficult to implement the full
system. I hope this has at least clarified a few things.

Bart

-- 
Before posting, please read the FAQ: http://sources.redhat.com/fom/ecos
and search the list archive: http://sources.redhat.com/ml/ecos-discuss


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]