should people skip lines between commands in a mod template?

This forum is now closed as part of retiring phpBB2.
Forum rules
READ: phpBB.com Board-Wide Rules and Regulations

This forum is now closed due to phpBB2.0 being retired.
asinshesq
Registered User
Posts: 6266
Joined: Sun Feb 22, 2004 9:34 pm
Location: NYC
Name: Alan

should people skip lines between commands in a mod template?

Post by asinshesq » Sat Dec 03, 2005 1:24 pm

I've been involved in an interesting discussion in another thread about whether mod authors should be skipping a space between each action and the next command for template readability. Ptirhiik - RPGnet-fr correctly points out that it is important for mod authors to be able to unambiguosly tell the user when skipped spaces are supposed to be inserted into the final modded file and when they are not, and for that reason he argues that mod templates should include no skipped lines other than those the author wants to see reflected in the final modded file.

That's fine if everyone were following that rule, but my sense is that over 90% of the mods in the phpbb mod database skip a line before each command to enhance mod template readability. Unfortunately, the way easymod works those skipped spaces get inserted into the final modded file even when the author does not intend that, and that of course hurts readability of the final modded file. That means that the great majority of mods incorrectly add spaces when installed via easymod.

Rather than telling mod authors they should not be skipping lines (which most of them would ignore), I would like to see easymod changed so that it follows the following rules:

- if there are no skipped lines between commands, that's fine (it should continue to work the way it currently works)

- if there is one skipped line between the end of one action and the very next command, ignore the skipped line because that's just the mod author making the mod readible but is not an indication that easymod should insert any skipped lines in the final file

- if there are more than one skipped lines between the end of one action and the very next command, insert into the new file that number of skipped lines minus one.

So in every case where ther are skipped lines the very last skipped line before a command is treated as template spacing for neatness rather than an indication that a new line should be inserted...but if the mod author wants to insesrt skipped lines he can just skip more than one space.

If we have an established rule, I don't see why there would be any confusion about whether or not to insert skipped lines. In fact, to the contrary, under the present scheme there is massive confusion. If easymod is not changed it will insert incorrect skipped lines when it installs most of the current mods (doesn't hurt functionality of course, but it does interfere with readability).

What do other people think?

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Re: should people skip lines between commands in a mod templ

Post by Ptirhiik » Sat Dec 03, 2005 4:04 pm

asinshesq wrote: (../..)if there are more than one skipped lines between the end of one action and the very next command, insert into the new file that number of skipped lines minus one.
This would make the manual installation completly silly, don't you think ?

A way to split better your template - as I understand it is your concern, is to simply add a commented line :

Code: Select all

#
#---[ SOME ACTION ]---------
#
do this and that
#
#
#---[ NEXT ACTION ]------------
#
You can also use something like that :

Code: Select all

#
#----[ SOME ACTION ]-------------
#
do this and that
#
#################################
#
#
#---[ FIND ]-----------------
#
blah blah
#
#------[ SOME ACTION ]-------------
#
do this and that
#
#################################
Both will give the expected result both with manual and automatic installation. These are only two quick ideas, I'm pretty sure others will have better.


But really, this :

Code: Select all

#
#---[ FIND ]---------
#

blah
#
#---[ AFTER, ADD ]-----
#
blah2

#
#---[EoM]------
is not the same than

Code: Select all

#
#---[ FIND ]------
#
blah
#
#---[ AFTER, ADD]------
#
blah2
#
#---[ EoM ]-----
Think ie of the mail tpls.

Swizec
Former Team Member
Posts: 1701
Joined: Mon Mar 10, 2003 9:42 pm
Location: Slovenia
Contact:

Post by Swizec » Sat Dec 03, 2005 4:24 pm

I use spacing in all my mod templates and I think it makes the whole thing more readable, even more, it makes it more obvious where stuff has been inserted when checking the modded file

Kind of like this:

Code: Select all

# 
#---[ FIND ]------ 
# 

blah 

# 
#---[ AFTER, ADD]------ 
# 

blah2 

# 
#---[ EoM ]-----
I doubt that anyone who is doing it by hand actually inserts those blanks though, I know I never did

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Post by Ptirhiik » Sat Dec 03, 2005 5:49 pm

> Swizec : ok, explain me how you come from the first to the second :

language/lang_english/email/admin_welcome_activated.tpl

Code: Select all

Subject: Account Activated
Charset: iso-8859-1

Hello {USERNAME},

Your account on "{SITENAME}" has now been activated, you may login using the username and password you received in a previous email.

{EMAIL_SIG}

Code: Select all

Subject: Account Activated
Charset: iso-8859-1

Hello {USERNAME},

Your account on "{SITENAME}" has now been activated, you may login using the username and password you received in a previous email.

__________________________

Be sure to visite the FAQ : {U_FAQ}
And to accept our posting policy : {U_RULES}
__________________________

{EMAIL_SIG}

asinshesq
Registered User
Posts: 6266
Joined: Sun Feb 22, 2004 9:34 pm
Location: NYC
Name: Alan

Post by asinshesq » Sat Dec 03, 2005 5:56 pm

Swizec wrote: ...I doubt that anyone who is doing it by hand actually inserts those blanks though, I know I never did

THe more difficult problem is that easymod will stick a ton of skipped lines in your final files if you do that and that makes your final files harder to read. I was hoping to create a consensus that easymod shouldn't be doing that even if you do skip a single space (but if you skip more than one space easymod would then recognize it). If we had that consensus, maybe the powers that be would tinker with easymod to make it behave in accordance with the consensus.

Swizec
Former Team Member
Posts: 1701
Joined: Mon Mar 10, 2003 9:42 pm
Location: Slovenia
Contact:

Post by Swizec » Sat Dec 03, 2005 6:39 pm

Never actually modded that but I believe that for EM it should be like this:

Code: Select all


#
#---[ FIND ]------
#

{EMAIL_SIG}

#
#---[ BEFORE, ADD ]------
#
__________________________ 

Be sure to visite the FAQ : {U_FAQ} 
And to accept our posting policy : {U_RULES} 
__________________________

#
#---[ EoM ]------
#

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Post by Ptirhiik » Sat Dec 03, 2005 7:17 pm

Sorry Swizec, but the thing and its contrary :
  • if you consider that line feed have to be ignored, you will find {EMAIL_SIG}. But the result will be :

    Code: Select all

    Subject: Account Activated
    Charset: iso-8859-1
    
    Hello {USERNAME},
    
    Your account on "{SITENAME}" has now been activated, you may login using the username and password you received in a previous email.
    __________________________
    
    Be sure to visite the FAQ : {U_FAQ}
    And to accept our posting policy : {U_RULES}
    __________________________
    {EMAIL_SIG}
    The linefeeds are missing and the exisiting text is sticked to the added.
  • Now if you consider the linefeeds have to be considered, you wont find lf/{EMAIL_SIG}/lf : the file ended just after {EMAIL_SIG}, with no extra blank line.
  • Let's consider a last possibility : ignore linefeed in FIND and consider them in ADD : there also it results in sticking {EMAIL_SIG} to the text added, as you skip the first lf prior {EMAIL_SIG}.

    Code: Select all

    Subject: Account Activated
    Charset: iso-8859-1
    
    Hello {USERNAME},
    
    Your account on "{SITENAME}" has now been activated, you may login using the username and password you received in a previous email.
    
    __________________________
    
    Be sure to visite the FAQ : {U_FAQ}
    And to accept our posting policy : {U_RULES}
    __________________________
    {EMAIL_SIG}
With a strict consideration of the mod template, you will have this :

Code: Select all

#
#---[ FIND ]-----------
#

{EMAIL_SIG}
#
#---[ BEFORE, ADD ]--------
#

__________________________

Be sure to visite the FAQ : {U_FAQ}
And to accept our posting policy : {U_RULES}
__________________________
#
#---[ EoM ]-------------

Swizec
Former Team Member
Posts: 1701
Joined: Mon Mar 10, 2003 9:42 pm
Location: Slovenia
Contact:

Post by Swizec » Sat Dec 03, 2005 7:21 pm

From what I udnerstand EM doesn't care about blank lines in FIND but does in ADD, ergo what I wrote would result in what you described, IF ran through EM...

no idea what would happen if someone was doing it by hand...

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Post by Ptirhiik » Sat Dec 03, 2005 7:28 pm

To be more picky, depending easyMOD version and the CR/LF encoding of the mod text description, EasyMOD considers linefeed found after fragments, wherever they stand inexisting, and before the fragment, existing. This means easyMOD does not a strict mod template analysis (what wasn't its aim, at contrary).

Manually applying the mod, with the way you wrote your description, chances are very high the user will issue to a lost of linefeed, so won't reach the result expected. With the way I wrote, I'm pretty sure (actually I have experimented this more than once :)), the user considers the linefeeds and issue to the good result. Results with easyMOD are hazardeous (see 1° paragraph for reasons) : the way I wrote usually succeed with easyMOD, but I also experienced some exceptions.

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Post by Ptirhiik » Sat Dec 03, 2005 7:48 pm

> asinshesq :

mod template obviously consider # char for no-code lines. EasyMOD does not comform entirely to this, preciasly because at the begining Nuttzy didn't want to make this tool a restrictive one, but a very large one (supporting heteroclit hack/mod templates, even multi-linguale).

When something doesn't introduce a flew, or a reduce of the possibilities, why not. There is not the case : adding linefeed as code line to ignore, you introduce a comfusion ("What to do ?"), and remove a very important possibility : the one to add linefeeds preciasly.

At this time, I don't know how to add a blank line at end of a added block ie, due to easyMOD, although I should be able to do this considering the mod template. Willing to mute also the linefeed prior a block (find or add), you loose entirely the possibility to add linefeed around a block except using a replace with the line before and the line after, not the best to do at least in tpls (nor in php btw).

By my side, I would like easyMOD to do exactly what I describe, not interpreting what I wrote : if I add a linefeed prior or after a block, that's because this linefeed has to be, and ignoring it may drive to an entire different result.

So maybe the mod template has to change, but in this case tell me how to proceed with the example I quoted above, which will be enough obvious for me as for a manual installer (asking users to count minus one line is not realistic : they will consider all or none). What is sure, is easyMOD has to be reviewed on this point to use an only method, not two depending the place.

Swizec
Former Team Member
Posts: 1701
Joined: Mon Mar 10, 2003 9:42 pm
Location: Slovenia
Contact:

Post by Swizec » Sat Dec 03, 2005 8:12 pm

From what I remember, aren't there plans for XML templates?

or has that been voted against... I kind of lost track

wGEric
Former Team Member
Posts: 8805
Joined: Sun Oct 13, 2002 3:01 am
Location: Friday
Name: Eric Faerber
Contact:

Post by wGEric » Sun Dec 04, 2005 3:25 am

If anyone wants to play around with the EasyMOD rewrite code, the you can view it here, http://cvs.sourceforge.net/viewcvs.py/easymod/easymod/ . To check out, follow the instructions on this page, http://sourceforge.net/cvs/?group_id=136984 (I just barely checked it in so it probably won't show up in the public CVS server for a couple of hours).

It should be able to install MODs and the FTP (php extension), and Server methods should be working. There is still a lot that needs to be done but if you want to report bugs in the install MOD process, then we will accept those. Bug reports on anything else will be rejected.

I haven't tested it on blank lines but I think the problems with line endings should be fixed. Anyways, now would be a good time to give feature requests on how you want to see EasyMOD advance.
Swizec wrote: From what I remember, aren't there plans for XML templates?

Yes, there are still plans for it. We are (slowly) working towards getting that implemented.
Eric

asinshesq
Registered User
Posts: 6266
Joined: Sun Feb 22, 2004 9:34 pm
Location: NYC
Name: Alan

Post by asinshesq » Sun Dec 04, 2005 4:46 pm

I've thought about this some more and I continue to think that mod authors should be able to skip a single line between the end of some code and the beginning of the very next template command. That substantially enhances readiblity of the template while at the same time allowing a mod author who wants to indicate insertion of some skipped lines to do so by having more than one skipped line after the end of some code. I don't thik it's a good idea to allow mod authors to skip needless lines between a template command and the code that follows it, however, because I think the template command and the code associated with it belong as a single logical unit.

I think almost all of the mods in the phpbb mod db are written the way I am advocating:

-- a template command is followed without any skipped lines by some code

-- after the code there is a single skipped line

-- after the skipped line there is the next template command

but easymod currently inserts extra spaces as a result of those skipped lines in a way that is against the mod author's intention. Do others agree with me?

User avatar
Ptirhiik
Registered User
Posts: 7411
Joined: Mon Jan 06, 2003 10:36 pm
Contact:

Post by Ptirhiik » Sun Dec 04, 2005 6:45 pm

Still a no-no to my point of view : this would be comfusing information, despite you have already # char existing : you can add as many # char you want, you won't comfuse users. Add lines any- and every- where, there you drive to mistakes.

I still don't get the point "it is more readable" : really, I don't think so, at contrary : if you don't know if you have to consider a linefeed because it is before or after a block, you can be sure there will be mistakes, as at least there is non-obvious interpretation. The more I consider a template with exta linefeed, the less I figure how a user can do the right move at first shot.

asinshesq
Registered User
Posts: 6266
Joined: Sun Feb 22, 2004 9:34 pm
Location: NYC
Name: Alan

Post by asinshesq » Sun Dec 04, 2005 7:01 pm

Ptirhiik - RPGnet-fr, I just went through the directory on my harddrive where I keep other people's mods and loked at the first 10 of them. Each and every one (including famous mods like the attachment mod and the admin_userlist mod) did what I am suggesting. In fact, the only mod author I know of who doesn't skip spaces is you. You may well be right that your way is much better, but no one is writing mods that way and I think we are better off changing easymod to conform to how the mods are actually written.

Post Reply

Return to “[2.0.x] MOD Writers Discussion”