Re: Developer manual update diff for checking

Again, all fixed bar one item (see below). New diff attached - am keen to see whether the moved </sect3> formats correctly in the HTML output.

Ian

On 2012-03-15, at 12:59 PM, Fabian Keil wrote:

> Ian Silvester <[email protected]> wrote:
> 
>> I've attached a diff of the updates I've made to the developer manual in
>> the New Release - OS X section. Please could someone check it for
>> buildability and correctness then let me know so that I may commit it.
> 
> 1)
> It doesn't build:
> 
> fk@mint ~/privoxy $ make dok
> [...]
> mkdir -p doc/source/developer-manual
> cd doc/source/developer-manual && jade -c /usr/share/sgml/docbook/dtd/3.1/docbook.cat -ihtml -t sgml  -D.. -d ldp.dsl#html ../developer-manual.sgml && cd .. && cp developer-manual/*.html ../webserver/developer-manual/
> jade:../developer-manual.sgml:2757:11:E: end tag for element "SECT3" which is not open
> make: *** [dok-devel] Error 1
> 
> This can be fixed by removing the "</sect3>" added by the
> last chunk of the patch.

Huh, yeah, I wondered about that. It seems that the sect tags cannot be nested? That closing tag matches that that opens the entire OS X section, so I've moved it to just before the first of the three sub-sections.

> 2)
> One trailing white-space. BTW, git can be configured to
> highlight those when viewing commits.

Thanks for the tip!

> 3)
> The indentation seems to be inconsistent compared to the
> patch itself and its surrounding.

The indenting of this file varies throughout (and worse the indents are not a consistent width, precluding the use of the tab key, regardless of whether it inserts spaces or tab characters). My changes are at least internally consistent and minimise the number of hard carriage returns necessary to wrap the lines correctly. This is my way of saying I don't want to fix this!

> 4)
> The "paragraph" starting with "There are three modules ..."
> is a single line when it probably should be three.

Corrected.

> 5)
> Typos: "pacakge(s)", "on it's usage".

Corrected.

> 6)
> Given that unlike the previous patch this one is intended
> for technically at least somewhat adept users, I think all
> the occurrences of "folder" should be replaced with "directory":
> http://www.lemis.com/grog/Rant/bad-language.php#folder
> 
> If all Mac OS X users know what a directory is, it might
> make sense to do it everywhere, but I'm aware that parts
> of the OS X documentation already used the word "folder"
> before your improvements.

Laziness on my part. I fought for many years to stick with 'directory' where those around me (note, mostly not Maccies) moved to using 'folder'. In the end I started to use it merely because it's quicker to type! That said I think that those Mac users who are keen enough to read and use the developer manual will understand the correct terminology, so I've corrected these to 'directory' so as to be in keeping with the rest of our documentation.

Ian

------------------------------------------------------------------------------
This SF email is sponsosred by:
Try Windows Azure free for 90 days Click Here 
http://p.sf.net/sfu/sfd2d-msazure

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