[Geany-devel] Changes to templates

[Matthew Brush]

On 03/15/11 14:10, Colomban Wendling wrote:
> Le 15/03/2011 21:08, Matthew Brush a écrit :
>> On 03/15/11 09:54, Colomban Wendling wrote:
>>> Le 15/03/2011 04:12, Matthew Brush a écrit :
>>>> Strip all leading and trailing whitespace on the text read from template
>>>> files.
>>>
>>> What if somebody *wants* whitepaces/newlines at the end of her template?
>>> I can easily imagine one wants this, for example for function
>>> descriptions [1] or whatever (it's seems to be the case with the Geany's
>>> default function template).
>>> Moreover, Geany's default templates seems to work OK without the patch,
>>> don't they?
>>
>> I noticed Geany's default templates end with 2 trailing newlines,
>> perhaps that should be changed to 1 to sort of "split the difference"?
>
> Not sure I understand what you mean, sorry :/ Could you rephrase please?

I mean if you `cat data/templates/gpl`, by default it has a trailing 
line (blank line at the end) and then Geany code adds another newline. 
My issue is that even if your template only has 1 newline at the end, 
Geany appends another one, so no matter what, it's not following what's 
in the file exactly.  It should be consistent, either read the file 
exactly, and don't append a newline, or strip all trailing newlines and 
append only the last one (to make sure */ ends up on its own line).

In case I'm still not clear on what I mean, I'll try to demonstrate:

In data/templates/fileheader:

   ====start====
   {filename}

   Copyright {year} {developer} <{mail}>

   {gpl}
   ====end====

In data/tempalates/gpl:

   ====start=====
   {filename}
   ...
   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
   MA 02110-1301, USA.

   ====end====

Notice, by default, there is 1 newline in the GPL template.  So you 
would expect the output comment block for fileheader to look like this:

   ====start=====
   /*
    * foo.c
    * ...
    * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
    * MA 02110-1301, USA.
    *
    */
   ====end====

But the actual output comment block looks like this:

   ====start=====
   /*
    * foo.c
    * ...
    * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
    * MA 02110-1301, USA.
    *
    *
    */
   ====end====

Notice the 2nd newline that gets added in here from somewhere.  I hope 
that makes sense.

So my idea is to 1) remove the 1 trailing newline from the template file 
(personal preference, others might disagree) and 2) make the code not 
add its own newline at the end (inconsistent, if it should be exactly as 
in file).

>
>>>> Fix filetypes.c to use /* */ style comments rather than C++ style
>>>> comments.
>>>
>>> I'd personally agree with this change, but it has a drawback: multi-line
>>> C comments can't be nested. So the comment/un-comment command becomes a
>>> little less useful since it'd break if commenting stuff including
>>> comments.

So it's ok in Java then?  (I don't think it's valid in Java).

>>
>> This is true, and I didn't think of this, however, I still don't agree
>> that for C filetype to insert "invalid" C code (by default).
>
> C++-style single-line comments are not invalid in C. They are invalid in
> ANSI C89 and ISO C90 (it's almost the same anyway), but totally valid in
> ISO C99, and supported by most compilers (when not in strict C89/C90
> conformance mode, of course).

I guess my point is that it should be lowest common denominator.  Where 
/* */ style comments are always valid, sometimes // comments are not.  I 
know it seems like a small problem, but it's really annoying having to 
create a .java file from template, and copy its file header into the C 
file, every single time I need a file header.

>
>>> Maybe a better fix would be to allow a filetype to define both
>>> single-line and multi-line comments, and use them when appropriate?
>>> (e.g. multi-lines comment for template comments, single-lines for ^E)
>>
>> Another way would be to let users embed the comments directly into the
>> templates, and not have it done automatically by software, letting the
>> user choose the indentation and comment style for those.
>
> I see 3 major problems at first glance:
> 1) comments are different in different languages (e.g. C and Python),
> would then need a template per language (please, no);

Good point.  It would at least have to be per lexer, which would be pain.

> 2) how would we nest templates without nesting comments? (e.g.
> fileheader includes gpl)

Also good point.  It would have to remove the comments first, then 
insert the template, and then re-comment the whole thing.  Probably more 
work than it's worth.

> 3) backward compatibility would most probably be lost.

Not sure what you mean by this, but probably also good point :)

The other thing I notice, since we're discussing it; shouldn't the 
Python "Function Description" insert a triple-quoted docstrings below 
the function def, not hash (#) comments above the def?  I don't think 
the hash-style comments would be understood by Doxygen, Epydoc, or 
Sphynx, for example, but I might be wrong.  I'm pretty sure it won't end 
up in the __doc__ attribute of the function though.

Cheers,
Matthew Brush