Community Input, XML 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.
wGEric
Former Team Member
Posts: 8805
Joined: Sun Oct 13, 2002 3:01 am
Location: Friday
Name: Eric Faerber
Contact:

Community Input, XML MOD Template

Post by wGEric » Thu May 05, 2005 9:06 pm

Sometime in the near future a new MOD Template will be avaliable for use. This new MOD Template will not replace the current one but provide more control for MOD Authors. The new template will use XML to provide speed and power for automatic installers and other parsers of the MOD Template. I will be refering to the new template as the XML Template and old, current template as the Text Template.

Like I said, we will be providing the XML Template so that the MOD Template is not only read faster by automatic parsers but so that Authors have more control over how their MODs are installed. A couple of ways this will be done is allowing regular expressions in FIND actions, control over what versions of phpBB MODs will be installed for, instructions for specific languages or templates, XML is a universal language, and much more. With XML being a universal language, install instructions can be translated on the fly to any language as long as the browser supports XSLT (When viewing the mock-up, you will see an example XSLT template. None of the language is hardcoded).

We, the MOD Team, will be providing tools to convert between the two different templates. If you don't understand XML, you can still use the Text Template and then convert it over to the XML Template with these tools, at the click of a button.

You can view our current mock up of the template here. View the source to see the actual XML. At this time I do not want to go through and explain every part of the XML Template. Although if you have any questions, please ask.

Here is where you, the community, come into play. We, the MOD Team, would like your input on the XML Template. Is there anything you would like to have added? Is our XML syntax messed up? Is there anything we can change to make it better? This is your oppurtunity to provide us with what you would like.

We, the MOD Team, will review and weigh the pros and cons of each suggestion, but not necessarily implement each suggestion.

Along with this template, new actions for the Text Template will be added. More information on this at a later time.
Eric

A.I. BOT
Registered User
Posts: 1848
Joined: Thu Apr 17, 2003 11:43 pm
Location: Newfoundland, Canada
Contact:

Post by A.I. BOT » Thu May 05, 2005 9:41 pm

Iv had an idea like that for some time now but never got around to doing it :)

I think its great good job eric.

User avatar
naderman
Consultant
Consultant
Posts: 3735
Joined: Fri Aug 01, 2003 10:06 pm
Location: Berlin, Germany
Name: Nils Adermann
Contact:

Post by naderman » Thu May 05, 2005 10:22 pm

Great to see the xml-arization of the MOD template ;-) I also like you added an XSLT Stylesheet which makes the shiny XML look even prettier ;-) It's bringing the MOD Template to todays standards and will help automatic installation and standardize MODs even more I hope :)

I hope the MOD Description will become language specific, because I often have to explain what a MOD does to people. Simply because they are not able to read the english description included in the installation file. Or does

Code: Select all

	<meta name="language" content="en-AU" />
mean you have to copy the whole XML file for each language? (<diy-instructions> should be translatable too)
Some more information on

Code: Select all

            <mod-config>config.modcfg</mod-config>
would be nice and I would like to know what format

Code: Select all

                <date>2004-07-26T00:00:00.0000000+10:00</date>
uses. I don't really see the need for T00:00:00.0000000+10:00 in the MOD History.
It would also be nice if you could decide on spaces or tabs for the example file so it's a little easier to read ;-)

For the file alteration part I don't really like the huge amount of tags used here. Wouldn't it be nicer to just have

Code: Select all

       <edit target="includes/constants.php">
instead of

Code: Select all

        <open src="includes/constants.php">
            <edit>
I also don't know why you called it "src".
You could also replace these tags to make it less confusing:

Code: Select all

<inline-action type="after, add"> to
<action type="inline-after-add">

<action type="after, add"> to
<action type="after-add">
and so on. These would render the <inline-edit> tag useless. An edit would consist of exactly 1 <find>, 0 or 1 <inline-find> and exactly 1 <action>. Less tags, less complexity, more understandable structure. How will language changes and auth changes be done with this system?

I hope I could help you a little bit ;-)

naderman
I appreciate gifts from my Amazon wishlist.
naderman.de twitter: @naderman

User avatar
MHobbit
Former Team Member
Posts: 4761
Joined: Thu Mar 18, 2004 5:32 pm
Location: There and Back Again

Post by MHobbit » Thu May 05, 2005 10:25 pm

Very cool. :)

I don't have any suggestions... right now, at least.
Former phpBB MOD Team member
No private support is offered.
"There’s too many things to get done, and I’m running out of days..."

User avatar
Flaming_cows
Registered User
Posts: 761
Joined: Sat Jul 05, 2003 1:43 am
Contact:

Post by Flaming_cows » Fri May 06, 2005 12:47 am

Last I checked, we don't orbit a 'Hyrogen' sun. As for suggestions regarding the xml, I'll have to post back. The XSL looks very nice though.

Kinfule
Registered User
Posts: 706
Joined: Tue Mar 02, 2004 12:16 am
Location: Chile

Post by Kinfule » Fri May 06, 2005 3:07 am

I wonder if Easymod will be able to install mods in this format?

User avatar
smithy_dll
Former Team Member
Posts: 7630
Joined: Tue Jan 08, 2002 6:27 am
Location: Australia
Name: Lachlan Smith
Contact:

Post by smithy_dll » Fri May 06, 2005 6:01 am

naderman wrote:

Code: Select all

                <date>2004-07-26T00:00:00.0000000+10:00</date>
uses. I don't really see the need for T00:00:00.0000000+10:00 in the MOD History.
It would also be nice if you could decide on spaces or tabs for the example file so it's a little easier to read ;-)

Thats a product of the Microsoft XML parser. It somehow came about by setting the fields dtd definition to date. The timezone etc... will not be required, but inclusion of will not lead to denial depending on the field type eventually set in the formats dtd.
naderman wrote: For the file alteration part I don't really like the huge amount of tags used here.

Organisation and grouping of actions, also helps the DTD enforce where actions should go.

One of the good things is by using a standard dtd, all you need to validate the MOD is the W3c XML validator.
Last I checked, we don't orbit a 'Hyrogen' sun.

See wikipedia: Subn
I wonder if Easymod will be able to install mods in this format?

EasyMOD will be updated in the future to support this format, however there isn't much point now to mass support a format thats still in drafting.



I am willing to take any suggestions on how to include translations of the DIY step...

User avatar
naderman
Consultant
Consultant
Posts: 3735
Joined: Fri Aug 01, 2003 10:06 pm
Location: Berlin, Germany
Name: Nils Adermann
Contact:

Post by naderman » Fri May 06, 2005 6:12 am

smithy_dll wrote:
naderman wrote: For the file alteration part I don't really like the huge amount of tags used here.

Organisation and grouping of actions, also helps the DTD enforce where actions should go.

One of the good things is by using a standard dtd, all you need to validate the MOD is the W3c XML validator.


You should not use grouping where it is not needed. Using a Schema (also supported by the validator) instead of a DTD you can enforce the order of elements without of groups. I don't think you should use more tags which make it more difficult to understand for people not used to XML only because you cannot set the order of elements in a DTD. The <open src=> tag hasn't really anything to with this though. It should at least be replaced with <file path=> cause that is what it really is. If it was an "open" it would make more sense to have it as <open src="x" /> and not as a container for other elements.
smithy_dll wrote: I am willing to take any suggestions on how to include translations of the DIY step...


Just give it a lang="" attribute and allow it to be used several times (for each language).

naderman
I appreciate gifts from my Amazon wishlist.
naderman.de twitter: @naderman

User avatar
Flaming_cows
Registered User
Posts: 761
Joined: Sat Jul 05, 2003 1:43 am
Contact:

Post by Flaming_cows » Fri May 06, 2005 7:18 am

Yeah, I meant to ask why you were using a DTD and not a schema. Also, I think maybe you could add some tags for compatibility requirements beyond phpBB version such as requiring the Multi-BBCode mod (as an example for a 2.0.x MOD).

User avatar
smithy_dll
Former Team Member
Posts: 7630
Joined: Tue Jan 08, 2002 6:27 am
Location: Australia
Name: Lachlan Smith
Contact:

Post by smithy_dll » Fri May 06, 2005 9:18 am

Blah, I meant schema and not DTD, sorry.

An explanation of the grouping seems in order. The grouping is highly semantical markup that corresponds to how a document is edited.

You open a file, so we've grouped all the file edits by the file. Each file can have multiple edits. The only time that it's acceptable to put multiple FIND statements in an edit is when your narrowing in on a search. So all FINDs are listed first, followed by all ACTIONs then lastly all INLINE-EDITs.

In other words, an EDIT corresponds to all the edits made at the place in code the last FIND leads you to.

It also forces order in any computer parser so logical EDITs can't get muddled up even if someone and goes and sorts the list of EDITs for some reason.


I disagree on the reability thing, it only adds a single line above and below and doesn't do much to change the already readability of XML. It is not intended for people to directly read the XML, but rather for that to be a storage medium where they will load an XSLT onto it, or load it into easyMOD. The XSLT will probably end up including links to knowledge base articles outlining how to do each step in installing the MOD. There is also a very good usability reaons why people shouldn't be reading the XML source directly, but rather using an XSLT. This is because of how < is mapped to > in XML etc... (XML escape characters, & " < etc...).

I will consider <file path="">, the reason I hadn't used it is because in an earlier revision it was used for a section that mimics the File to Edit, and/or (can't remember which exactly) the Included files section of the Text Template.

I hope all that made sense, we are open to ideas still... 8) (I can be wrong sometimes too)

User avatar
naderman
Consultant
Consultant
Posts: 3735
Joined: Fri Aug 01, 2003 10:06 pm
Location: Berlin, Germany
Name: Nils Adermann
Contact:

Post by naderman » Fri May 06, 2005 9:54 am

smithy_dll wrote: Blah, I meant schema and not DTD, sorry.

I already wondered why you were linking to a schema validator for a DTD ;-) It would be nice to see the schema file as well (and it should be referenced in the xml file).
smithy_dll wrote: An explanation of the grouping seems in order. The grouping is highly semantical markup that corresponds to how a document is edited.

You open a file, so we've grouped all the file edits by the file. Each file can have multiple edits. The only time that it's acceptable to put multiple FIND statements in an edit is when your narrowing in on a search. So all FINDs are listed first, followed by all ACTIONs then lastly all INLINE-EDITs.

In other words, an EDIT corresponds to all the edits made at the place in code the last FIND leads you to.

It also forces order in any computer parser so logical EDITs can't get muddled up even if someone and goes and sorts the list of EDITs for some reason.


Ok, seems like I misinterpreted this part a bit, I thought an EDIT must only be 1 EDIT and not multiple in-line EDITs. In this case it makes more sense to group them, cause the INLINE-FIND - INLINE-ACTION relaction would not be clear without of the container element.
smithy_dll wrote: I disagree on the reability thing, it only adds a single line above and below and doesn't do much to change the already readability of XML. It is not intended for people to directly read the XML, but rather for that to be a storage medium where they will load an XSLT onto it, or load it into easyMOD. The XSLT will probably end up including links to knowledge base articles outlining how to do each step in installing the MOD. There is also a very good usability reaons why people shouldn't be reading the XML source directly, but rather using an XSLT. This is because of how < is mapped to > in XML etc... (XML escape characters, & " < etc...).

I was thinking about writing the XML, not reading it, however I understood why you group them now.
smithy_dll wrote: I will consider <file path="">, the reason I hadn't used it is because in an earlier revision it was used for a section that mimics the File to Edit, and/or (can't remember which exactly) the Included files section of the Text Template.

I hope all that made sense, we are open to ideas still... 8) (I can be wrong sometimes too)


Thanks for clearing this up, however I found another thing:

Code: Select all

                <inline-edit>
                    <inline-find type="regex">
				abc{0-9}
			</inline-find>
                    <inline-action type="operation">{0}++</inline-action>

                </inline-edit>
Shouldn't the first regexp use ( instead of { for the subpattern and shouldn't {0} refer to the whole pattern instead of the first subpattern? And because phpBB is written using php I would prefer $0 over {0} ;-)

naderman
I appreciate gifts from my Amazon wishlist.
naderman.de twitter: @naderman

User avatar
battye
Extension Customisations
Extension Customisations
Posts: 10933
Joined: Wed Feb 11, 2004 11:02 am
Location: Australia
Contact:

Post by battye » Fri May 06, 2005 11:39 am

I'd like to see the top section in Verdana size 10, in 12 it looks strange. Smithy I think it was mentioned tabs or spaces, I vote tabs :)
Customisations Team Member

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

Post by Ptirhiik » Fri May 06, 2005 12:49 pm

One word : please, please, enforce author's notes ! They are just lost here in the middle of low interest notes. They should be first or second to have a chance to be read.

Some questions :
- do you plan a converter between the both formats ? This XML format is really more verbose than the actual one, and unreadable for a user without a tool, which is really not convenient for a copy/paste through an editor way to install...
- how will be handled added carriage returns in front of the text to find, or the text to add ? As far as I remember, the XML parsers remove them,
- is it wise to provide two install script, with the differences that may occur between both (consequence of the two question above :)) ?

User avatar
naderman
Consultant
Consultant
Posts: 3735
Joined: Fri Aug 01, 2003 10:06 pm
Location: Berlin, Germany
Name: Nils Adermann
Contact:

Post by naderman » Fri May 06, 2005 1:17 pm

Ptirhiik - RPGnet-fr wrote: - do you plan a converter between the both formats ? This XML format is really more verbose than the actual one, and unreadable for a user without a tool, which is really not convenient for a copy/paste through an editor way to install...
wGEric wrote: We, the MOD Team, will be providing tools to convert between the two different templates. If you don't understand XML, you can still use the Text Template and then convert it over to the XML Template with these tools, at the click of a button.
;-)
Ptirhiik - RPGnet-fr wrote: - how will be handled added carriage returns in front of the text to find, or the text to add ? As far as I remember, the XML parsers remove them,

In a schema file you can specify whether leading and trailing whitespaces(including newlines) shall be removed from the data. However I don't know whether XML parsers act correctly.

naderman
I appreciate gifts from my Amazon wishlist.
naderman.de twitter: @naderman

User avatar
smithy_dll
Former Team Member
Posts: 7630
Joined: Tue Jan 08, 2002 6:27 am
Location: Australia
Name: Lachlan Smith
Contact:

Post by smithy_dll » Fri May 06, 2005 3:37 pm

Both Microsoft and I'm pretty sure the PHP XML parser treats whitespace inside a tag thats defined as a text (string) containiner as literal characters. This isn't XHTML, so think of every thing in <find> as being inside the XHTML <pre> tag.

Yes there will be a convertor and the process should be transparent to regular users.

While inclusion of the Author Notes field has always been mandatory, I don't think it's ever been mandatory to put anything in it (I won't deny you for it anyway). The DIY "action" is being introduced into both the XML and the Text formats to draw attention to the installer to actually do what would normally be listed in the Author Notes.


Part of the plan to make this transparent to the end-user are, XHTML translation to aid and assists manual installation. Convertors between the two format when the feature sets used overlap between the two specifications. And of course easyMOD.

One of the advantages of XSLT, is javascript can be embedded to say 'copy this block to the clipboard', again this is all still preliminary.

As for the XML source code tabs vs spaces, it makes absolutely no difference to anyone unless they are actually inside a <find> tag etc...

Lastly as for fonts on the XSLT, lets hammer the format out first before being fickle over a style which will probaby change ala subSilver2.0 ;)

Locked

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