[scribus-dev] Breakdown of Scribus source code.

[John Culleton]

On Wed, 6 Jan 2016 18:03:05 +0000
Craig Bradney <cbradney at scribus.info> wrote:

> 
> 
> > On 6 Jan 2016, at 17:40, William Bader
> > <williambader at hotmail.com> wrote:
> > 
> > 
> > > Date: Wed, 6 Jan 2016 11:01:34 -0500
> > > From: John at wexfordpress.com
> > > To: scribus-dev at lists.scribus.net
> > > Subject: Re: [scribus-dev] Breakdown of
> > > Scribus source code.
> > > 
> > > On Tue, 5 Jan 2016 17:40:36 +0000
> > > Craig Bradney <cbradney at scribus.info> wrote:
> > > 
> > > > 
> > > > 
> > > > > On 5 Jan 2016, at 15:59, John Culleton
> > > > > <John at wexfordpress.com> wrote:
> > > > > 
> > > > > I am about to embark on a project to
> > > > > list the C++ modules of Scribus in an
> > > > > hierarchical list such as
> > > > > Top module
> > > > > module x
> > > > > module y
> > > > > module aa
> > > > > 
> > > > > Where modules x and y are called from
> > > > > Top module and module aa is called from
> > > > > module y etc. 
> > > > > 
> > > > > In other words a kind of a hierarchy
> > > > > chart without the graphics.
> > > > > 
> > > > > I am going to do this just for my own
> > > > > use in understanding the structure of
> > > > > the stuff I compile every night. If
> > > > > there is another tool to assist in my
> > > > > understanding of what fits where please
> > > > > point me to it. I really don't want to
> > > > > reinvent the wheel. 
> > > > > 
> > > > > -- 
> > > > > 
> > > > 
> > > > I started something on the wiki that
> > > > documents some of this awhile ago. It's
> > > > only very basic though.
> > > > 
> > > > http://wiki.scribus.net/canvas/Source_Code/scribus
> > > > 
> > > 
> > > Useful nonetheless. Thanks.
> > 
> > 
> > Would using a system based on special
> > comments in the source be easier to maintain?
> > 
> > Someone has already run Scribus 1.5 through
> > doxygen: http://fossies.org/dox/scribus-1.5.0/
> > 
> > Regards, William Bader, Director of Research
> > and Development at SCS,
> > http://www.newspapersystems.com
> > 
> 
> Sure
> 
> Doxygen can be run to produce that. The stuff
> is all in the source already but the comments
> don't exist in the code to define the design or
> decisions made.
> 
> Craig

In my misspent youth  wrote programs in (gasp!)
COBOL. The creator of that language considered
incode documentation to be important enough to
devote the first  of four divisions to that
purpose.

Later stewards of that language have stripped out
most of that structure. But I still find it
useful. If you use grep on all my programs and
subprograms searching for the keyword "REMARKS"
you will get the name of each unit followed by a
brief description of its purpose. Here in all its
glory is my model IDENTIFICATION DIVISION:

000010 IDENTIFICATION DIVISION.
000020 PROGRAM-ID. CLASSIC.
000030 AUTHOR. JOHN CULLETON.
000040 INSTALLATION. WEXFORDPRESS Eldersburg MD.
000047 SECURITY. Copyright 2010 John R. Culleton, Jr. 
000048 DATE-WRITTEN. TODAYS-DATE.    
000050*REMARKS. THIS IS A TEMPLATE FOR OPEN COBOL AND HTCOBOL.  

The line numbers and all-caps format are obsolete,
even for COBOL. but I am a traditionalist. 

Other useful features from the dim dark past: 
Programs were named indicating the major system
they belonged to:
ACT001 (accounting)
INV001 (inventory)
PAY001 (payroll)
ORD001 (order entry)
etc.

to the extent practical within a program each
paragraph had a name that began with a number
indicating which major function they were 
part of:

100-MAIN-LINE.
110-OPEN-FILES.
120-PROCESS-DATA.
(etc.)

Enough. A well defined and suitably concise set
of rules can make understanding of the code and
maintenance thereof easier. 

 
-- 
John Culleton
Wexford Press
Book layout, typesetting and Indexing
Free list of books for self-publishers:
http://wexfordpress.net/shortlist.html