Re: Developer manual update diff for checking

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

> Ian Silvester <[email protected]> wrote:
> 
>> 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.
> 
> sect tags for the same level can't be nested.
> You can use sect4 tags inside sect3 tags and while I missed
> this previously, this is probably what you are looking for.
> 
> The current version builds as well, but the connection between
> the sections isn't clear and for example "OSXPackageBuilder module"
> is 6.3.9 instead of 6.3.8.1.

Was afraid that might happen. Am using sect4 as appropriate now and nesting within the sect3.


>>> 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!
> 
> I missed that fact that you are mixing tabs and spaces for indentation.
> If a tab spans eight spaces on your system, it might explain why you
> consider your indentation consistent. Replacing the tabs with spaces
> should fix that.

Hadn't realised I was doing so until you pointed it out. It seems the editor I was using has a rather strange way of handling tabs VS spaces-as-tabs. Very annoying. That said, there is no consistency at all in this regard in the rest of the document. I have consequently chosen arbitrarily to use spaces alone with a tab width of 2 and reformatted the OS X section accordingly.

Ian









> That being said, having updated documentation is more important
> than the style issues which can always be fixed later.

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

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