Re: new release documentation

On 1/6/13, Fabian Keil <[email protected]> wrote:
> 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 ...

Well this is just peachy - 'make dok' fails for me now :

$ make dok
Setting doc version and status to 3.0.20, UNRELEASED
rm -f -r doc/source/*bak doc/source/*/*bak
Setting docs to not stable 3.0.20
rm -f -r doc/source/*bak doc/source/*/*bak;
rm -f doc/webserver/developer-manual/*.html
rm -f -r doc/source/developer-manual
mkdir -p doc/source/developer-manual
cd doc/source/developer-manual && openjade  -ihtml -t sgml  -D.. -d
ldp.dsl#html ../developer-manual.sgml && cd .. && cp
developer-manual/*.html ../webserver/de
veloper-manual/
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

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

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

ok - thanks, I'm still struggling to understand the make file

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

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

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

Lee

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