Subject: Re: (Lack of) Source Code Documentation
From: Martin Sevior (msevior@mccubbin.ph.unimelb.edu.au)
Date: Sun Dec 23 2001 - 16:19:45 CST
On Sun, 23 Dec 2001, j.m.maurer wrote:
> Thx Martin for your explanation! Now I have another question: what do
> the layout classes do?
AbiWord has a nice Model - View -Controller architecture. In abiword out
Model is the PT_PieceTable Classes. Our controler code is split between
fv_View (which is the interface to the currently active document) and
PD_Document.cpp which actually manipulates the PieceTable.
The PieceTable is simply a collection of document fragments. Each fragment
represents contiguous collections of formatting properties. These
properties are simply a list of const char * strings consistiting of
(property, values). These apply over the entire fragment. Like
(font-family, Arial), (font-weight, bold). That is all they are in the
piecetable.
The layout classes fl_DocLayout, fl_SectionLayout, fl_BlockLayout, fp_run
fp_Page interpret these properties and produce the document
from them.
The distinction between the fl_* classes and the fp_* classes is that the
fl_ classes deal with content on a logical level without reference to
actually placing it on page/screen. The fp_* classes actually place the
text on the page/screen.
> > ==> Suppose I want to do the following: I want to write a new view of
> the document which does noting more than diplaying only the plain text
> of the document (no styles ect). I suppose I have to create a new View
> class for interaction with this plain text view and I have to write a
> new Layout class that represents the document as a whole bunch of chars,
> am I right? If not, please correct me... any help would be greatly
> appreciated!
>
You need to write new fl_SectionLayout, fl_BlockLayout, fp_Run, fp_TextRun
code. These would basically igore all the piecetable information you
weren't interested in. You could get by with a just a new enum value in
the the fv_View.cpp::ViewMode variable.
Cheers
Martin
> Marc aka Uwog
>
>
> On Sun, 2001-12-23 at 04:46, Martin Sevior wrote:
> > Hi Uwog,
> > You're right about the lack of documentation. We're slowly
> > correctinbg this via the Doxygen utility. Th e idea is to add Doxygen
> > comments in the course of regular hacking activity. We generally now
> > always include Doxygen comments for every we new method we write and we
> > rquire these from submitted patches, never-the-less there is stiull a long
> > way to go.
> >
> > fv_View in particular has has no entry from he main doygen browsing page.
> >
> > http://www.abisource.com/doxygen/
> >
> > Actually fv_View has a lot more documentation than is available from
> > doxygen. There must be some kind of bug in doxygen's generation.
> >
> > In any case, fv_View is the interface between the user/event system and
> > the layout classes of the current view and document.
> >
> > In ascii art one might think of it like this.
> >
> > [user]
> > ap_EditMethods.cpp
> >
> > fv_View fv_View fv_View fv_View
> > Layout classes Layout classes Layout classes Layout classes
> > \ | / |
> > \ | / |
> > \ | / |
> > \ | / |
> > pd_Document pd_Document
> > Piecetable Piecetable
> >
> > Since a document can have multiple views on it and abiword can handle many
> > open documents simultanouesly.
> >
> > A lot ot the methods in fv_View have acquired doxygen comments over the
> > last 12 months but somehow they haven't prograged into the toplevel site.
> >
> > Cheers
> >
> > Martin
> >
> >
> > On Sun, 23 Dec 2001, j.m.maurer wrote:
> >
> > > Ha all!
> > >
> > > I'm new to AbiWord and trying to get a grip on the code. But since there
> > > is virtually _no_ source code documentation, this is a very difficult
> > > thing to do. Even major classes like fv_View don't even include an
> > > abstract of what they do!
> > >
> > > The number of active developers on AbiWord is fairly low, and I think
> > > the almost complete lack of source code documentation is a major factor
> > > in this.
> > >
> > > What I would propose is that a fair amount of (boring) work on this is
> > > done after the 1.0 release. This may attract more developers (at least
> > > on: me), which is a Good Thing(TM)!
> > >
> > > Are there any plans on this?
> > >
> > > Marc aka Uwog
> > >
> > >
> > >
> > >
> >
> >
>
>
>
>
This archive was generated by hypermail 2b25 : Sun Dec 23 2001 - 16:20:00 CST