[dev] Docs Module (was: Horde Summary Layout options, in HEAD maybe?)

[Ryan Gallagher]

Quoting Eric Rostetter <eric.rostetter@physics.utexas.edu>:

> Quoting Ryan Gallagher <ryan@studiesabroad.com>:
> 
> > Quoting Chuck Hagenbuch <chuck@horde.org>:
> > 
> > > > Other "considered" additions:
> > > > 1) A documentation/faq module
> > >
> > > This is on my list, too, to integrate with Whups. The Category:: code is
> > > _perfect_ for storing FAQ-type data, imho. I just haven't had the time
> to
> > > devote to it yet...
> 
> Interesting idea.  I'll keep that in mind... :)  One of the biggest problems
> with maintaining the faq list is trying to figure out where an FAQ should
> go within the FAQ structure...

FAQs are a simple document type, and would be an ideal canidate for 'first
implementation' testing. Not to mention EXTREMELY useful.

> 
> > area.  In my personal brainstorming I was considering playing with an XML
> > based document manager type thingy.

Neither do I exactly.  I should have put it in quotes ;-)

> I'm not sure what the "document manager type thingy" is, but I think all
> docs should go to XML.  Then use XSLT to translate to text, pdf, html, etc.

Agree'd completely here.

> > I was intrigued by the use of XMLSchema to define possible document types,
> 
> I'd rather see us use an existing XML format than create new ones, if
> possible.

This intrigued me for several reasons. For end user and technical documents,
obviously there are  many pre-existing DTDs or even Schemas about.  But I wasn't
just envisioning a "documentation" system, but a more versitle "document"
system.  Document examples might include:

 - Expense Reports
 - Form Letters
 - Meeting Notes
 - Process/End User Documentation (like you were envisioning)
 - FAQs (like you indicated)
 - Standardized 'Purposal' type documents
 - Office Documents (such as Vacation Request Forms, etc etc)
 - For where I work, things like Course Descriptions, Course Syllabi,
Itineraries etc might be included in this list.
 - etc...

Essentially a method and system for defining any commonly used document type in
a office/community enviroment. Hence my desire to have the available document
types be dynamic and 'pluggable'. This is also where the "web-editable" feature
i'd love to see comes into play.  For the documents vary in nature and the
audience of authors would likely range equally far and wide.  Hence the desire
to avoid CVS as the sole means of changing and updating documents.  But there is
no reason that CVS couldn't remain the backend (along with other options).

But obviously setting it up for read-only web access is a much easier problem to
tackle initially.

> > The viewer engine would rely on a the XSL->html style definitions.  Other
> > output
> > formats could later be added given the right processing tools and presence
> of
> > an appropriate stylesheet.
> 
> Not sure about the viewer (could the help viewer be expanded to handle more
> stuff like this?).  But I'm definately in favor of XML docs -> XSLT
> stylesheets to multiple output formats.
> 
> > The web-editable requirement is "gray area".
> 
> I'm not sure it has to be web-editable.  Just web accessible, or cvs 
> accessible, or both (since chora *does* both, I'd be happy with current
> setup).
> 
> > I suppose that an
> > upload/download tool plus the viewer engine would be useful enough by
> > themselves to start with.
> 
> Chora/CVS is an upload/download tool, and any XSLT engine (or browser 
> supporting XSLT) could be the viewer... Or maybe I totally misunderstand
> you..

I meant a more "user" oriented upload/download tool. Provided they could graps
the XML basics to author a document outside of the system.

> > I mentioned the mild interest in a structure document diff tool for Chora
> a
> > while back in chora@.  I suppose this would be the ideal backend.  Then
> 
> I'm also still interested in that, but I see no real relationship to this 
> project, and I've had no time to pursue chora work.

True, not really related.

> > despite
> > the web-centric nature of the docs, they could be fully versioned and
> easily
> > associated with a "make" process to facilitate building of offline formats
> > for all or parts of the document catalog.
> 
> I think it would be XML nature, not web-centric nature.  And CVS would give
> you versioning.  Make would be simple if you have an XSLT engine (like that
> php provides via sablotron).  I think we might have to provide already 
> converted versions for those who don't have access to, or simply don't know
> anything about, and XSLT engine.

I think we mostly agree here, the web-editable aspect was the only issue that
was in serious question.  That and the option for varying document types.

-- 
Ryan T. Gallagher
ryan@studiesabroad.com
International Studies Abroad
http://www.studiesabroad.com
(512)480-8522