Re: Privoxy documentation updates

Hi all,

See below for the background; a discussion of the pain we are experiencing with using DocBook to manage the documentation.

The upshot is that whilst I'll commit minor changes to the .sgml files directly, I intend to post diffs of larger changes to this list. If those of you who have a working DocBook environment (does anyone?!) could then test that my changes a. do not break the documentation build and b. seem sane, please post back on thread and I will only then commit them.

Kind regards,

Ian


On 2012-03-09, at 3:05 PM, Fabian Keil wrote:

> Ian, I think this should be discussed in public on the mailing list
> so everyone is kept in the loop. If you agree to this, please reply
> to the list instead of in private.
> 
>> I'm afraid I am going to have to admit defeat in getting DocBook to
>> produce HTML files on OS X. I have successfully installed DocBook, the
>> necessary SGML-related libraries and openjade, but have hit subsequent
>> problems.
> 
> What a surprise ...
> 
>> First of all the various DTDs and catalogs are not stored in the
>> locations expected by the configure and make scripts so I cannot use the
>> 'normal' workflow.
> 
> The "'normal' workflow" doesn't work on FreeBSD either.
> The only platforms where I know it works (for some definitions
> of "works" and only after some fiddling) are Debian and some
> other GNU/Linux distributions.
> 
>> This meant that I have had to piece together what seems to be the
>> correct command line for openjade from the makefile and configure
>> scripts and ensure that the ldp.dsl modification made by configure was
>> manually entered correctly. I'm pretty confident I have done this
>> correctly - it's not hard to follow the logic of the configure script to
>> see how it constructs the JADECAT and JADEBIN parameters and then see
>> how these are used in a given build target.
>> 
>> Despite my efforts openjade still spews a ton of output (both warnings
>> about sgml elements and then the content of the page) and fails to
>> generate the HTML files. See the attached file.
>> 
>> I find it odd that the -t parameter is set to sgml in the makefile,
>> since my understanding of jade is that -t is the output format. Set this
>> way the output seems to go to stdout. If I deviate from the makefile
>> setting and try -t html, I do not get the output to stdout (I still get
>> a ton of warnings about undefined or incorrectly defined elements) but
>> nor do I get any file created.
> 
> Given that replacing the DocBook mess is on the TODO list
> I came to the conclusion that getting it to work on FreeBSD
> is a huge waste of time. Fixing one issue usually unmasks
> the next one, so measuring progress is futile.
> 
> As I gave up on fixing this on FreeBSD, I'm probably not in
> a good position to help you getting it to work on Mac OS X.
> 
> If it doesn't work on Mac OS X either, it probably means
> we should give ditching DocBook a higher priority.
> 
>> So what to do. I'm still keen that the documentation updates occur and
>> I'm happy to make changes, but unless you can suggest any hints to help
>> me get openjade working I cannot test my sgml source file changes and
>> hence am not happy to commit them. I could supply you with diffs for you
>> to test and commit? What do you think?
> 
> While committing untested changes is frowned upon in general,
> I think the DocBook mess warrants an occasional exception to the
> rule, especially if the change is minor (e.g. a spelling fix).
> 
> I do not always test minor DocBook changes right away either,
> as doing so involves booting up my GNU/Linux test system.
> 
> And like I mentioned before, DocBook changes that have been tested
> on one system aren't guaranteed to work on other systems anyway.
> Some jade flavours seem to be more strict than others.
> 
> If you post larger diffs to the mailing list I (or anybody else)
> can test them, but I think it's important that you commit them
> yourself, so the attribution doesn't get hidden.
> 
> In case of minor changes I'd recommend that you simply commit
> them untested for now, just like everybody else does ...
> 
>> Separately, is it an absolute requirement that the lines in the sgml
>> source files do not exceed 80 columns in length? I can't find an
>> sgml-recognising editor for the Mac so having to ensure I carriage
>> return at the 80th column is a bit of an annoyance.
> 
> It's closer to a guideline than an absolute rule and currently
> only followed by about 94% of the current non-empty lines anyway.
> Unless you significantly worsen the ratio I wouldn't expect
> any complaints.
> 
> Fabian

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/