[Yanel-dev] Re: [Dev] Upper case filenames

[Guillaume Déflache]

Michael Wechner schrieb:
> Guillaume Déflache schrieb:
>> Michael Wechner schrieb:
>>> I have noticed that you like to use a mix of Lowser and Upper case 
>>> filenames ;-)
>>
>> Any specifics?
> 
> YANEL_HOME/src/webapp/htdocs/GoogleAnalytics/GA.xslt (and page-GA.xslt , 
> ../commons/Id.xslt)
> 
> btw, just to make sure what GA.xslt and page-GA.xslt are doing, IIUC
> 
> GA.xslt: Is adding the actuall Google analytics code, right?
> 
> GA-page.xslt: is acting like a header file containing the imports, 
> includes, right?

Correct.

The GA.xslt should have initially been imported from a second 
stylesheet, that's why the splitting it made sense then and not so much 
anymore... :/


> commons/Id.xslt:  Identity transformation, right?

Ditto, tried to make that clear in comments as it gets used very often, 
but I forgot to clarify the filename, the maths metaphor wasn't good 
enough! ;)


>>> AFAIK Windows doesn't make a difference between lower and upper case 
>>> and IIRC we had some problems in the past because of that.
>>>
>>> A quick search on Google I found for example
>>>
>>> http://www.linuxquestions.org/questions/linux-general-1/same-filenames-in-a-directory-with-different-case-747704/ 
>>
>>
>>
>> As your quick search found, the only real problem that I ever 
>> encountered with case and filenames is when *in the same directory* 
>> there are two files which have the same name except for the case used, 
>> which I agree can be very confusing for humans as well.
>>
>>
>>> which doesn't really apply to us, but the point is that it can lead 
>>> to problems, so I would suggest that we keep to lower case.
>>>
>>> WDYT?
>>
>> I see no point of being over-cautious there, but maybe if you have 
>> more concrete examples I am happy to discuss them.
> 
> The problem is once we start with this, others will start as well and we 
> will risk that we get into trouble at some point
>> I mean Java class names are not all lower-case after all, and this has 
>> been never been a problem AFAICR.
> 
> right, because it's a common understanding to start java classes with 
> Upper case, whereas the emphasis is on common understanding ;-)

OK, so it seems what you are concerned about is more naming conventions 
than case problems, the problem is, we don't have naming conventions for 
everything (maybe only Java/JS really), and in particular AFAIK we don't 
for XSLT.


So here are a few XSLT naming guidelines/best practices I have come across:

- differentiating decorating XSLTs (where main input and output XML are 
the same, e.g. XHTML) from styling ones (that transform one format to 
another, e.g. Docbook to XHTML):

   - decorating: use xsl:transform as root element, use ".xslt" as file 
extension

   - styling: use xsl:stylesheet as root element, use ".xsl" as file 
extension

- indicating the main output format of styling XSLTs: add "-<format in 
lower-case>" just before ".xsl", e.g. element-xhtml.xsl, list-json.xsl, 
entry-atom.xsl, etc.

- don't put "transformation", "stylesheet" or similar in the filename, 
that's what the extension is for

- variable/mode/template names: use a namespace to avoid polluting the 
users's; not sure for parameter names: they may be defined externally 
and there is probably not always a namespace aliasing facility in all 
these external contexts

- in general for all identifiers: use '-' instead of '_' or CamelCasing, 
e.g.


That's not much but maybe it might help.