Re: [DotGNU]WikiTexi (was documentation/manual tool and DotGNU Task List)

[Jonathan P Springer]

On Tue, Feb 05, 2002 at 01:52:13AM +0000, Iain Hallam wrote:
> Jonathan P Springer wrote:
> 
> > After the mails that have flown around regarding documentation, I've 
> posted
> > the result of some research and thinking I did at
> >
> >    <http://members.bellatlantic.net/~vze2mqqv/wikitexi-req.html>
...
> (referring to v1.1)
> Functional requirements
> =======================
> - "Support the generation of additional documentation formats (e.g.
> manpages, docbooks, HTML)."
> 
> I'd also add a paged format to this list (e.g., PDF). The current set
> looks somewhat biased to formats that generate presentation on the fly.

Agreed.  I'll add it to the examples list.

> - "Make edit history available for perusal."
> 
> And, by extension, available for a full roll-back strategy?

Ah, you're catching up with me too quickly.  I realized in the shower
this morning that documents would need something akin to CVS's
"releases", as well as a "latest" flag.  I'm going to start thinking in
earnest about URI's later this week, and will take that into
consideration.

> - "Track document initiator..."
> 
> Would it be clearer to make that the owner?

Probably.  I'll rewrite.

> - "Provide for importation of existing documents in well-structure
> syntaxes (e.g. Linux docs, TexInfo)"
> 
> (Above text should say "well-structured") This may be pie-in-the-sky, 
> but it might eventually prove possible to extract some meaning from 
> older HTML or Word documents, for those companies/individuals that have 
> a large investment in existing technologies. This is waaaay in the 
> future, though... :-)

To sleep, perchance to dream... Truthfully, the companies/individuals in
question would probably need to be responsible for coding their input
XSL based on their understanding of their document content.  I rate it
as wish-list for now.
 
> Commentary and Annotations
> ==========================
> - "The 'Notes' functionality of the PHP Manual provides an excellent 
> example of such functionality."
> 
>   I don't think this is a good UI for notes. I believe that annotations,
>   etc. should appear near the text (or images) to which they refer. The
>   text says that "each note is associated with a particular document
>   node (URI)", which I agree with, but a user should be able to refer to
>   something smaller than a paragraph. I'd suggest a .GNU interface that
>   puts <span> tags into the text to mark annotations, were it not for
> | the fact that elements cannot overlap. Then each annotation could be
> | marked with a bar next to the commented lines, much as this scentence
> | has been picked out of the containing paragraph. Different annotations
>   could have nested bars.

Perhaps anchors instead of spans?  An annotation could define its range
based on one or two anchors.  Presentation, or course, is left as an
exercise for the student.

> Annotations should also be able to identify the version of the document 
> that they annotate. If the annotated paragraph disappears in a new 
> revision, the annotation no longer has much meaning. I think this part 
> of collaboration needs more investigation.

Well, we could let annotations define open-ended version ranges, plus if
the anchors disappear, so do the annotations.  I agree, this needs a lot
more thought.

> Document Structure
> ==================
> One thing that might trip up the invisible nature of document 
> transformations is that each output has different capabilities. It might 
> be wise to settle on a standard that will be emulated by those formats 
> that can't otherwise cope. This way, the semantic richness of DocBook 
> (OK, it's not that rich, but compare it to HTML) could be used as a 
> base, and then rendered each time to the intended format, but losing the 
> meaning.

Oops. We need to be clear on "transformation" vs. "presentation".  I
wasn't.  "Transformation" implies that all meaning is preserved.
"Presentation" means (to me) that something readable that conveys
meaning (e.g. PDF :-) ) is produced.  Most of what WikiTexi would do
would be presentation.  To date, Docbook appears the most likely first
target to shoot for as an internal representation framework.
 
> WikiTexi Architecture
> =====================
> I don't particularly mind what architecture is chosen, but I would 
> ultimately like something that could use DocBook or some other ASCII 
> format for basic storage in addition to the RDBMS option. I'd stretch as 
> far as a UTF encoding on this as well for i18n.

To work from the back forward. I've got no problem with UTF/Unicode
encoding.  Heck, it should be supported in RDBMS (darned idealism).  The
highly fragmented nature of collaborative editing makes me leery of
wandering too far afield from some sort of database.  I come from a data
warehousing background, which may be what makes me lean towards RDBMS.
I'm targetting this toward a high volume of edits; 
 
> In all, as I said above, I like the approach, and I'd like to get 
> involved with this (I'm still not profficient enough with .GNU to 
> contribute fully). I've been thinking about such a beast for a while, 
> although I had originally envisaged a Java front-end with a WYSIWYM 
> editor much like a jazzed-up outliner, so I've also got a few ideas on 
> the UI front.

Well, it looks like I'll be rewriting the article this weekend, anyway.
I'll leave a whole chapter for you if you care to contribute a
discussion of UI.  I think that various levels of UI will be needed,
based on the sophistication of the user -- Web for neophytes, Java for
those who can actually figure out how to install it.  I'll be happy for
any contributions -- UI is not my strong suit.

On a separate note, I have no idea right now how "DotGNU" this will be
by the time it's thought out.  I'm doing my best to keep it true to the
spirit of DotGNU; how closely it ties to the technology is still in for
a lot of discussion.

Cheers all,
-js

-- 
-Jonathan P Springer <address@hidden>
------------------------------------------------------------------------------
"A standard is an arbitrary solution to a recurring problem." - Joe Hazen