[Geany-devel] Changes to templates

[Colomban Wendling]

Le 15/03/2011 23:15, Matthew Brush a écrit :
> On 03/15/11 14:10, Colomban Wendling wrote:
>> Le 15/03/2011 21:08, Matthew Brush a écrit :
>>> [...]
>>>
>>> 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.

Actually, Geany *strips* one newline at the end of the finally-inserted
template. I know, regarding your example below (that is right), it might
sound weird, but let me show you:

A typical file on Unices *always* ends with a newline. So your templates
actually looks like:

  first-line\nsecond-line\nlast-line\n

This is OK, no problem: Geany strips this last "implicit" new line.
But now, try including a template inside another template:

my_tpl:
  first-line\nsecond-line\n

my_other_tpl:
  first-line\n{my_tpl}\n

Took alone, both looks OK. But now, parse my_other_tpl as expected, so
including my_tpl:

  first-line\nfirst-line\nsecond-line\n\n

...shit, we got two new lines. I'm not saying it's OK, just that this is
"logical" (read ahead).

> 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:
> 
> [...]
> 
> So my idea is to 1) remove the 1 trailing newline from the template file
> (personal preference, others might disagree)

I agree with this, I don't see why a license template would have an
extra newline at the end -- though it's not necessarily true with all
templates, for example in a function description template it would make
sense to have extra new lines at the end (or start) to include the
description.

> and 2) make the code not add its own newline at the end (inconsistent,
> if it should be exactly as in file).

As said, the code don't add new lines, though it's true the final result
actually looks weird.
What I propose is to strip the last "implicit" new line at the end of
all the loaded template files if they have one. This would fix your
issue (in an Unices world at least) IIUC.

Do you (all) think it's OK to strip the last new line of the end of
template files, since it's most likely to be an "implicit" new line?

Attached the possible patch, if you like to test it before.

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

No, even if I hardly know Java, I doubt nesting C-style comments is
valid in Java. Not sure why it's the default in the Java filetype...
does Java support C++-style comments?

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

I've already given my POV on this: I think ^E should use // comments and
templates /* */ in C. It "just" need to be implemented.
Too bad C don't have D's /+ +/ comments ;(

But in the meantime (hopefully :D), I still think that it's important to
keep nestable comments by default for ^E (maybe because I use ^E to
temporarily comment stuff out and rarely to create "true" comments).
And moreover, I think that if you prefer /* */ comments it's not *this*
hard to change your filetypes.c accordingly (although it's a bit a
power-user thing, I agree).

>> 3) backward compatibility would most probably be lost.
> 
> Not sure what you mean by this, but probably also good point :)

I mean that if somebody wrote his own templates, they wouldn't work at
all anymore (they'd miss the comment around); it'd not only be a few
newlines at the start or the end that would have changed.

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

This may be fixed by supporting two comment types per filetype, one
single-line (or at least nestable) to use with ^E, and one for
multi-line comments. Though, it wouldn't probably be enough for Python
since you still want to use sharp-comments in e.g. fileheader but
triple-quote-strings as comments for doc...
Maybe take a look at GeanyGenDoc, it should be able to do the right
thing (just need to teach it with the appropriate configuration file,
not done yet) -- and if it isn't able, file a bug report ;)


Cheers,
Colomban
-------------- next part --------------
A non-text attachment was scrubbed...
Name: templates-not-too-much-newlines.patch
Type: text/x-patch
Size: 2438 bytes
Desc: not available
URL: <http://lists.geany.org/pipermail/devel/attachments/20110318/3d13ecde/attachment.bin>