Re: new release documentation

Lee <[email protected]> wrote:

> On 1/6/13, Fabian Keil <[email protected]> wrote:
> > Lee <[email protected]> wrote:

> Well this is just peachy - 'make dok' fails for me now :
> 
> $ make dok
> Setting doc version and status to 3.0.20, UNRELEASED

It's probably not part of the problem, but "UNRELEASED" indicates
that GNUmakefile hasn't been generated with the latest configure.in.

> openjade:E: cannot find "none/html/docbook.dsl"; tried
> "../none/html/docbook.dsl", "../none/html/docbook.dsl",
> "/usr/share/sgml/none/html/docbook.dsl"
> openjade:E: specification document does not have the DSSSL
> architecture as a base architecture
> 
> It's late, I'll see if I can figure out the problem tomorrow

At the beginning of the thread you were using jade instead
of openjade.
 
> >> > I agree that Ian is a developer, but so are the rest of the
> >> > listed team members including yourself.
> >> >
> >> > In my opinion it would make more sense to simply not explicitly
> >> > declare David and myself developers to prevent any confusion.
> >> >
> >> > Another option would be to invent fancy titles for everyone ...
> >
> > This is still open for discussion.
> 
> I'm fine with being listed as a contributor & you certainly are the
> lead developer, so the current format is fine with me.  If you want to
> remove the titles I won't argue, but I do think you should be listed
> as lead developer, team lead or somesuch.  I'd rather not invent fancy
> titles.

In the context of free software projects I usually use the term
$project developer to refer to a member of the project who has
commit access and does anything that can be classified as developing
activity.

This includes packaging or fighting the documentation build system.

It's sometimes argued that it wouldn't cover "merely" documenting,
translating documentation or creating graphics but as currently
nobody does that anyway it doesn't matter for us.

On the other hand a $project contributor for me is someone who
has no commit access and interacts by sending patches, filing
bugs, helping out on the mailing lists etc.

I assume it's just a matter of semantics and if nobody has
a problem with the current list (due to interpreting developer
differently) we can keep it as is for now.

For reference the "Current Privoxy Team" consists of:

        Fabian Keil, lead developer
        David Schmidt, developer
        Hal Burgiss
        Lee Rian
        Roland Rosenfeld
        Ian Silvester

In some places (like the man page) there's a gap between the
"developers" and the "non-developers". The "categories" are
sorted by the number of commits made to "current" which may
or may not be intentional.

> >> Is 'make dok-tidy' a separate step one has to do manually?
> >
> > Currently it has to be done manually.
> 
> ok - thanks, I'm still struggling to understand the make file

Who doesn't.

> > It produces several screens
> > of output that might be interesting in some situations but would
> > push other output out of the scroll buffer.
> >
> >> I do a 'make dok' and it
> >> - doesn't run tidy on anything
> >> - doesn't run man2html even though the previous invocation failed
> >> - says "Documentation created." at the end
> >>
> >> I get  lots of cvs merge errors for things in
> >> /cvsroot/ijbswa/current/doc/webserver and my html source clearly has
> >> not been run through tidy:
> >>
> >> RCS file: /cvsroot/ijbswa/current/doc/webserver/index.html,v
> >> retrieving revision 1.63
> >> retrieving revision 1.64
> >> Merging differences between 1.63 and 1.64 into index.html
> >> rcsmerge: warning: conflicts during merge
> >> cvs checkout: conflicts found in current/doc/webserver/index.html
> >
> > This could be unrelated.
> 
> unrelated to my output hasn't been put thru tidy & yours has?

Unrelated to tidy at all.

I believe you get problems like this if you "cvs update" to 1.63,
somebody else commits 1.64 and you regenerate the file without another
cvs update first.

In my experience merging with cvs rarely works as expected if the
modified areas overlap. Before I started using git I therefore
preferred to always do it manually as it seemed easier than dealing
with the occasional merge fallout.

> > Merging with cvs works pretty poor in general (compared to tools
> > like git) and if you didn't cvs update to my latest changes before
> > regenerating the documentation I would expect merge issues
> > like this even if the changes are trivial.
> 
> It's late so I might well be missing something, but I think that until
> I can get the cygwin generated docbook output to look about the same
> as your generated output I just won't upload anything to the webserver
> directory.

Okay.

> >> > In my experience generating the HTML parts causes usually less
> >> > problems than the text parts (config, README ...) which at least
> >> > on my system always need manual intervention afterwards.
> >> >
> >> > If the HTML generation fails you usually get some kind of error,
> >> > but the text generation just silently produces garbage.
> >>
> >> Yes, a lot of garbage in at least config.new on my system, but it
> >> seems to be messing up just the long lines.
> >
> > Unfortunately unbreaking the long lines can't be easily automated.
> 
> I was looking for an option (markup?) that changed the output line
> width so the long lines wouldn't be split in the first place.  No joy
> yet.

I tried this in the past and there actually are parameters to specify
the line length, but if I remember correctly they just caused
different breakage as they also "optimised" short lines.

I'm sure that it is possible to fix this, but probably not without
some effort that could be better spend elsewhere (assuming we eventually
ditch the Docbook mess).

Fabian

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412

_______________________________________________
Ijbswa-developers mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/ijbswa-developers

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (FreeBSD)

iEYEARECAAYFAlDqv5EACgkQSMVSH78upWM0ngCfQCfP1ntM0Be0DQ9Xf8/2olSy
w4kAnA9LGR+gffWHDkXadkddjveyL/N+
=me5U
-----END PGP SIGNATURE-----