[as-devel] Re: AS documentation maintenance

Sasha Vasko/OSCA/Courts/Judicial(sashav@sprintmail.com)
Mon, 19 Mar 2001 09:27:05 -0600 


> * Andrew Ferguson (andrew@owsla.cjb.net) [010317 10:49]:
> >
> >     I'm replying to you offlist about this part becuase this is more of
> > a personal nature. When I was talking about a "transition period," what 
I
> > meant was that as of yesterday, the AfterStep developers have asked our
> > web/ftp master and docs maintainer to step down. He has been quite 
negative
> > about the project for the last several months, stating that it is 
"dead,"
> > when in fact the complexity of rewriting of AfterStep from scratch is 
so
> > great that it just seems as if nothing is happening. Hence, we are 
looking
> > for a new docs maintainer and if you would be interested, send a mail 
to
> > Sasha_Vasko@osca.state.mo.us. I'm sure he'd love to find out that a new 
doc
> > maintainer has been found. Welcome to the team!
> 
> Thanks a lot. I'm glad to help out any way I can.

Oh cool, wonderfull!

> 
> Sasha, I don't know if you've been following this, but I seem to have

Yeah, I don't do much e-mail reading over weekends :)
But I'm catching up on it.

> volunteered my services as a Documentation Pedant. There I was reading
> the list archives on tigr.net and thinking maybe I should subscribe and
> start answering questions. Well, seems like heading up documentation for 
AS
> would be a great way to do that. *grin*

Yes it will be.

Firstly few things you need to know about documentation :
AS documentation has 2 parts - FAQ and man pages. At the time FAQ 
maintainer is
Charlie Schimdt (aka ishamael), he's also as.themes.org maintainer.
man pages used to be maintained by David Mihm, and as a result of his 
negative 
stance towards 1.9 series of AS he's never updated them after 1.8 release.
I would really be happy to see someone enthusiastic to pick it up.

Now there is a difficulty in maintaineg man pages in the present state of 
AfterStep, as new options may appear. Sane choice would be to start from 
man page 
for aftertsep proper ( in src/afterstep ). Since that is what I've been 
working 
on mostly, and as the result its configuration code is the most complete 
one. 

libasConfig has another advantage as it gathers all the options together, 
and it is much easier to grasp hierarchy and logic then with older coding 
style.
files in libASConfig are named after actuall configuration files.
So for example if you want to check integrity of the base.#bpp file 
description in
the man page - you open up src/Config/Base.c and at the tom you'll find 
something 
like that :

TermDef BaseTerms[] = {<list of options> }

list_of_options lists all the valid options for base.#bpp Usefull 
information 
would be the quoted keyword ( obviously ) in column 2, data type in column 
4, and 
flags in column 1.
Most common flag is TF_NO_MYNAME_PREPENDING. What it does is it instructs 
ASCP not 
to append "*proggyname" construct in front of config option.

While checking man pages you have to go through the list of keywords 
present in 
man page and compare it to the list of options from the relevant file in 
libasConfig
whatever is missing - those are new things and has to be added. Note that 
MyStyle options are listed in include/confdefs.h instead, as they are 
embedded 
in different config files. Same goes for balloon config. 

Some of the options will have flags of TF_OBSOLETE - those are obsolete 
options 
and provided only for verbose error reporting.

TF_DEPRECIATED options are still supported but user will get wanring 
message 
and ASCP will never write those options into a file

I still need to stick couplle of TF_DEPRECIATED into Look.c  - I'll do it 
asap.

There is a possibility for hierarchical config structures, like MyStyle for 
example.
in this case you'll get name of the variable in the last column of the 
option 
definition, like : 
{TF_NO_MYNAME_PREPENDING,"MyStyle", 7, TT_QUOTED_TEXT, MYSTYLE_START_ID, 
&MyStyleSyntax}

MyStyleSyntax - points to the subconfiguration 

Respectively you'll need to reflect that in man pages by using indentation 
or something else.

Unlimited level of nesting is allowed, and in case of Wharf it is 
recurrent.

If you have any further questions - please feel free to ask. I'm always on 
#afterstep channel on openprojects.net 9:00 till 5:00 US Central Time.

If you decide that you like what you see and produce any usefull results - 
send them to me as a patch for review and if it looks good we'll add commit
access to CVS server for you.

> 
> > PS - The web/ftp master and docs maintainer had offered to resign in 
the
> > past, so it's not as if we'd fired him. It's just the best move for the
> > project to have a more opptomistic fellow in those roles.
> 
> Sounds reasonable.
> 
> I am to understand, then, that you need a new webmaster and webspace? If
> you don't have someone in mind, I might be able to help out there too. I
> don't want to come in with guns blazing or anything, but I do have a
> good deal of html experience and I am a sysadmin. Anyway, one thing at a
> time, eh?

Well, we are still in the state of uncertainity as to what will Dave Mihm,
do so it is a bit early to talk about new maintainers for fao and wao.

> 
> Look forward to hearing from you.
> 
> /i.

Cheers
Sasha Vasko