Re: new release documentation

Lee <[email protected]> wrote:

> On 1/6/13, Fabian Keil <[email protected]> wrote:
> > Lee <[email protected]> wrote:
> >
> >> On 1/5/13, Lee <[email protected]> wrote:
> >> > The developer manual builds OK for me and the user manual looks like
> >> > it's just (mainly?) missing a few "</sect3>" lines.
> >
> > Apparently even the syntax errors don't always "work" cross-platform ...
> 
> My docbook software is less forgiving than yours?

Or it might just complain about different things ...

> >> > I'll start working on the fixes unless someone else would rather do it.
> >>
> >> Well.. that was easy!  Copyright date needs to be bumped, Ian isn't
> >> listed as a developer and 3.0.20 isn't marked as beta are the obvious
> >> things that need fixing.
> >
> > Are you referring to the "Current Privoxy Team" section?
> 
> Yes, but it's my mistake.  I was looking at the privoxy man page on my
> system and it hadn't been regenerated.  What I get now for the man
> page is
> man2html: bad invocation
> 
> *sigh*

It's regenerated now.

Note that we have three different targets for man page generation.
"make man" gets me a result similar to the one you are describing
but apparently "make man2html" gets the invocation right ...

> > 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.

> >> Suggestions on how to share the results welcome.  I created a .zip
> >> file of current/doc/webserver but at 807KB it's probably too large to
> >> email as an attachment.
> >
> > In general you can simply push documentation changes to CVS
> > (which I just did for the less problematic HTML parts), preferably
> > after checking the diff to make sure there aren't too many gratuitous
> > white-space changes.
> 
> I think I better not do that -- at least until I can get my output
> closer to yours.
> see below
> 
> > Theoretically the dok-tidy target should prevent this for the
> > HTML parts, but I don't know if the output is stable across
> > platforms.
> 
> Is 'make dok-tidy' a separate step one has to do manually?

Currently it has to be done manually. 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.

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.

> > 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.

> Oh well..  it looks like I can help with updating sgml files but not
> with generating the final documentation :(

No problem, every bit helps.

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. ON SALE this month only -- learn more at:
http://p.sf.net/sfu/learnmore_123012

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

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

iEYEARECAAYFAlDpzGkACgkQSMVSH78upWPZKACfWhWeeLs1uTlIxBF7Dj7vmo5l
ZhQAoIVid+TfTTzt7JGYHeNK7b/UsVkl
=gZAr
-----END PGP SIGNATURE-----