Re: LHpi 2.7/2.8 and howto/documentation
Posted: 24 Feb 2014, 13:23
Agreed. I will try to keep the template self-documenting, but refrain from adding multiple conflicting example implementations. In return, the wiki can hold examples, including but not limited to, the ones already present in the template.anthonybe wrote:From my opinion, the template file should contain the minimal information about properties/functions and their usages (e.g. examples), and the How-to should be a reference where developers can find/share more completed examples (e.g. different scenarios like the foil/regular prices on same page).
Sounds good to me.I'll keep on checking for them and resolving them, and you keep on adding themanthonybe wrote:You can find some "TODO" in the how-to for points that i'm not sure about it or I didn't know how to describe in the good wayLordHelmchen wrote:Please do point out anything that you're unsure about, so I can verify it.
I agree on the howto being structured in order of implementation priority, and will leave the ordering to you (as I'm probably biased).anthonybe wrote:For the structure, I tried to make it like a wizard where each required properties are coming first and afterwards optional properties and LHpi properties. At the end, the functions to define.
In my case, I "reformatted" your sitescript template in that order.
If the how-tov and template file have the same structure, developpers can read the how-to and complete their sitescript at the same time. They know what the property/function does and how-to fill it.
I disagree with reordering the template:
- Boolean control options are placed in front. Some are potentially needed to be already define for the rest of the sitescript, including function definitions, to execute properly. They also are the only thing the end user should need to edit once the template becomes a released sitescript, so having them accessible at the front makes sense.
- global configuration elements (like libver,dataver,scriptname) and the global container tables (LHpi and site) need to be defined for the rest of the script to execute properly.
- site configuration elements (regex,resultregex,currency,encoding) could be moved down and grouped with the tables, if that seems more convenient or logical.
- running the sitescript with undefined functions will result in LHpi (intentionally and conrolled) throwing an error, while running with empty tables will usually just find nothing to import, so functions were placed above tables due to priority.
Will do. I rather like seperating Development (of the library) and Developing (sitescripts for the library) in this way.anthonybe wrote:The hint are welcome in the how-to, in the appropriate section.LordHelmchen wrote:Should the paragraphs from the Hints for developers section stay seperate or be moved over to the howto?
"multiple copies of the same script" could be added in the "(semi-optional) Name of sitescript".
"procedure of funtions call" could be added in separate section (e.g. annexes ?).
"Dropping card" could be added to the appropriate function definition (ParseHtmlDate, BuildCardData, ...) depending the usage developpers do.
"non trivial tables" could be added as a general tips in the properties introduction.
Will do (eventually) Feel free to start it, adding TODO markers where needed.anthonybe wrote:You're welcome to add these infos in the how-to.LordHelmchen wrote:Shall I add information about the return values that LHpi expects from the sitescript functions, or are the template comments enough for this?
Last (for this post, anyway ) remark about the wiki: I'm not documenting changes I make to the wiki in this thread. In this phase of rapid changes to the documentation, I regularly check the wiki's history function and would propose you do the same.
As I'm working towards libver 2.8, I already expected the need for and planned to add "updating sitescripts" sections to the howto, where I will try to document all needed changes.anthonybe wrote:-----------------------
Apart of the wiki page, I have another question about LHpi.
- Library updade
...
Until that exists, you can either continue using the library version you're most comfortable with (sitescripts were made to be able to specify and load their preferred library version for this reason), or you may need to use some sort of
- diff | Open
In any case, it is probably a very good idea to use ImportPrice from the template version that matches the library version, and only incorporate changes you might have made to it into the the new function definition.
I apologise for the inconvenience this causes.
I will only maintain the template for the latest library version, but library and data versions will stay up in their respective sections as long as there is any current sitescript that depends on that version (and even if not, old versions can still be downloaded via the version history).
I just love when that happens. See the first two entries in trader-onlineDE version history for my favorite moment so faranthonybe wrote:Different url infix for same set
In the last days, the Belgian website did an important update, causing the failure of the my sitescipt.
2.8 will bring an extended site.frucs format, that better deals with importfoil="n" or "o" cases:anthonybe wrote:...
Do you think it's the correct way ? Or you see another one ?
- new site.frucs structure | Open
Should I hurry and release 2.8 (and continue going to 2.9), so you can use this already?
- 2.7 -> 2.8 changes done so far | Open
- plans for either 2.8 or 2.9 | Open
feel free to run wild with itanthonybe wrote:(Still a good example to add in the how-to )