fsfe / reuse-tool

reuse is a tool for compliance with the REUSE recommendations.
https://reuse.software
411 stars 149 forks source link

Support Apache Velocity template files #553

Open nicorikken opened 2 years ago

nicorikken commented 2 years ago

I encountered .vtl and .vm files in the wild, which are template files for Apache Velocity. More about the comment syntax in the VTL Reference.

Especially the single line comment is a difficult one, requiring some refactoring for support for the trailing **:

## This is a comment. **

The multi-line is easy to implement:

#*
  This is a multiline comment.
  This is the second line.
*#

I'll make a simple PR for the multi-line comment, leaving this issue as a reminder to work on a change for the comment handling to support trailing markers in single-line comments.

mxmehl commented 2 years ago

Thanks, LGTM so far.

Regarding the trailing whitespace, two comments:

  1. Does the syntax really require a whitespace?
  2. The tool could learn to write an empty line when the line will just contain the whitespace.
nicorikken commented 2 years ago

I did some more searching and I found that whitespace is not required, going by https://velocity.apache.org/engine/devel/user-guide.html#comments Let me copy the examples here:

## This is a single line comment.
This is text that is outside the multi-line comment.
Online visitors can see it.

#*
  Thus begins a multi-line comment. Online visitors won't
  see this text because the Velocity Templating Engine will
  ignore it.
*#

Here is text outside the multi-line comment; it is visible.
#**
  This is a VTL comment block and
  may be used to store such information
  as the document author and versioning
  information:
    @author John Doe
    @version 5
*#

I didn't know about the latter, but that might be most relevant as it is intended to document information about the document, just as SPDX headers do.

New proposal So on second thought I think it makes sense to change it so we end up with:

#**
SPDX-FileCopyrightText: MyOrg

SPDX-License-Identifier: AGPL-3.0-or-later
*#

I can modify the pull request accordingly.