About the Standard Documentation Proposal

[Cornelius Schumacher]

On Tuesday 17 February 2004 16:45, Ismael Olea wrote:
>
> First of all, I think we need the most general solution we can afford.
> Web libraries as TLDP.org or ES.TLDP.org share almost exactly the same
> problem as the personal document management on a desktop or in a
> multiuser server.

I'm not sure it helps to aim for the most general solution. A working 
implementation which works for both GNOME and KDE would be better than 
something more general which could work for everybody, but doesn't  get 
implemented.

> Other point, IMHO, is the unquestionable need of using XML/W3C
> technologies as our data base. I'd thought nobody would prefer other
> alternatives but found that .desktop proposal and, sincerely, seems to
> me it don't fit in the web view neither the system wide use. Having an
> XML data system we can be sure we are ready to the next future whatever
> it'll be.

I wonder how you come to the conclusion that the need for XML is 
unquestionable. The desktop file solution works very well, is easier to write 
and parse and I fail to see how this choice would affect our ability to adapt 
to the future in any way.

> About the ScrollKeeper approach, I'm really happy with it, at least in
> the wide perspective. It seems to me to be very elegant and flexible and
> adaptable to the system-wide and distributed web use. For example you
> can use it to add _all_ the documentation in a present linux system into
> a comprehensive documentation manager. This is absolutely _great_ for
> compatibility with legacy systems (like the ancient man and info
> systems). The fail of a more wide use of it I think is in the
> distribution packagers, who could use the ScrollKeeper services no
> matter the application is, in the same way you can express in a RPM file
> what files are documentation using an special instruction.

The need to merge the XML data after installation of new documentation makes 
Scrollkeeper a very unattractive mechanism for packagers. This doesn't fit 
well to modular packages.

Adding all documentation of a linux system to the documentation manager is no 
problem with the proposed meta data proposal.

> I think ScrollKeeper can be used even for registering remote documents
> into the local doc management system, which is very suggesting for me.

The current KDE documentation system implementation based on desktop files 
already supports remote documents.

> About the problem that developers had had creating OMF.xml files, it is
> obvious for me a set of tools is needed to help in the creation and
> maintenance of them. That tools will work as an automated QA control.
> And I have the opinion that documentation and software publishing has
> lots of similarities, so, as you can suppose, a set of "auto-tools" for
> documentation are needed to, specially if you try to propose the use of
> conventions/restrictions in the creation and managing of documentation
> in order to have an almost 100% automatic management, with QA control
> and flexibility.

Adding documentation to the documentation system should be as simple as 
possible. I doubt that creating some "auto-tools" for that purpose would 
really make it simpler.

-- 
Cornelius Schumacher <schumacher at kde.org>