On 06/14/2011 11:58 PM, Stuart Henderson wrote:
> On 2011/06/14 15:43, Jason McIntyre wrote:
>> On Tue, Jun 14, 2011 at 03:58:46PM +0200, Florian Obser wrote:
>>>
>>>>
>>>> if you want to document it, i'd prefer to try and tuck it in nice and
>>>> neat, without an example. how about rearranging the section to something
>>>> like this:
>>>>
>>>> Comments can be put anywhere in the file using a hash mark
>>>> (`#'), and extend to the end of the current line. The
>>>> current line itself can be extended using a backslash (`\').
>>>>
>>>> Additional configuration files can be included with the
>>>> include keyword, for example:
>>>>
>>>> include "/etc/pf/sub.filter.conf"
>>>>
>>>> ...
>>>>
>>>> that would be just a one line addition.
>>>>
>>>> i'd prefer to try and keep this little blurb short, as i think we
>>>> should expect readers to understand the idea of `#' as comments,
>>>> and `\' as extending the current line.
>>>>
>>>
>>> Right.
>>> The problem is what happens when you combine `#' and `\' on the same
>>> line. pf.conf does one thing, extending the comment. ksh (for example)
>>> does something else, ignoring/commenting the `\'. I'm not sure if your
>>> addition captures this distinction.
>>>
>>
>> ah, i missed that part. i think the text i proposed still makes it clear
>> that it would work this way but admittedly it does not address it head
>> on.
>>
>> so i'm not fussed. i'll leave it to stuart to decide whether the example
>> is actually needed or not. i suppose if it is different to the shell, it
>> will confuse people.
>
> I think it needs to be mentioned explicitly as, although it's something
> people coming from a programming background might expect, it's completely
> alien to people who only edit configuration files and common scripting
> languages.
As an anti thesis you could change the behaviour of the parser.
But that probably needs documentation, too.
This might have the benefit of being what users expect.
>
> You're right about it getting copied to other places, there are 9
> copies in tree and I'd rather not come up with an example for each,
> so I would be happier to have it in the text rather than as an
> example if it can be done clearly, but I haven't managed it...
>
After reading jmc's proposal many more times I finally convinced myself
that I would probably understand that comments will be extended, too.
I think it's nearly there, maybe a tiny bit more explicit?
Comments can be put anywhere in the file using a hash mark
(`#'), and extend to the end of the current line.
The current line itself, including comments, can be
extended using a backslash (`\').
Additional configuration files can be included with the
include keyword, for example:
include "/etc/pf/sub.filter.conf"
I don't feel strongly one way or the other (change the parser or extend
the documentation). It took us about 15 minutes to debug our original
problem so we are not going to forget pf.conf's behaviour any time soon.
It would be nice to do one thing or the other...
Thanks,
Florian
