Re: Developer manual update diff for checking

On 2012-03-17, at 8:04 AM, Fabian Keil wrote:

> Ian Silvester <[email protected]> wrote:
> 
>> 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.
> 
> Builds correctly.
> 
>>>>> 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.
> 
> The rest of the file doesn't look too inconsistent to me.

It certainly varies in terms of use of tabs and spaces-as-tabs, meaning that the indentation is variable throughout the file depending on the tab width setting of the editor in which the file is viewed, hence my choice to avoid tabs entirely. Still and all at least it builds and the content is more correct than before.

> Note that the mostly consistently messed up indentation
> of the <programlisting> sections is intentional as they
> get translated into <pre> sections, which means the amount
> of white-space affects the rendering.

Gotcha - live and learn - I've corrected these. Hopefully this'll be the last diff (of this change!) you'll have to review ;o)

Ian







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