Grf2Html [0.5.2 released - 2010-05-02]

[frosch]

Well, the title says everything :p
This tool converts .grf files into .html files. The output is supposed to be easier to read than plain nfo.
It shall support all grf features as of current NewGraphicSpecs (last changed 2010-05-02).
About the usage and limitations read "readme.txt". Also read about the licence (GPL v3) in "COPYING.txt".

The output of the program is meant for semantically checking your nfo code. (Like: Did you really code, what you wanted to code? Or did you run into a special case of nfo, you did not knew of?)

Do not try to find syntactical errors with this tool. Use NFORenum it that case.
Though Grf2Html can print some errors about the grf, they are only meant for indicating, that Grf2Html has not understood something.
So generally use Grf2Html only on grfs, you have previously checked with NFORenum.
If Grf2Html prints errors in the output, read the "readme.txt" about what to do with them. It will tell you, whose fault they are.


Some sweet features of Grf2Html:
1) Properties, Variables (and some more things) are printed together with their name (taken from NewGrfSpecs-Wiki and TTDP source documentation).
2) References to Action1 Sets, Action2s, Action10 Labels and Action7/9 jump targets are hyperlinked.
3) Industry-Layouts are arranged like they are build.
4) Station/House/Industry-Spritelayouts are printed with a preview of the defined bounding boxes.
5) Spritenumbers in the Spritelayouts are split up into sprite, recolor-sprite and the other flags.
6) The entries in ActionF name parts are printed with their real probabilities (inclusive the "extra probability" if the sum of all relative probabilities is not a power of 2).
7) RecolourSprites are printed in a way, that makes it easier to see the changes.
8) UTF-8 strings and TTDPatch string codes are detected and put in the output.
9) Sprites belonging to the same ID of the same feature are grouped.


NewGrfs with a lot of images or spritelayouts can be very slow depending on your operating- and file-system (especially when the file system is on the network). This is because the output can consist of ten thousands of small files. Simply copiing the output to a different location takes nearly as long as it took Grf2Html to create the files in the first place. The '--nodata' option can be useful in that case. See readme.txt for details.


Installation instructions:
1) Take the binary for you operating system from below, and extract it to your favorite location.
2) Read "COPYING.txt".
3) Read "readme.txt".
4) Proceed further as stated in "readme.txt".


The sourcecode is now hosted on the same svn server as GRFMaker:
[url]svn://grfmaker.zernebok.net/projects/grf2html[/url]
The instructions for compiling are in the "readme.txt".


Changelog (of latest release):
Version 0.5.2 - 2010-05-02
- Update to current NewGrfSpecs:
Add variable 0x25.
Add global property 0x12.
Add house variables 47, 66 and 67.
Add railtype properties and variables.
Add airport tile properties and variables.
Add action7/9 conditions 0x0D and 0x0E.
Add lots of new languages to Action4.
Add support for additional groundsprites in spritelayouts.
- Remove: Old 'new airports'.
- Change: Print usage on invalid command-line options.
- Fix: Do not store binary included files using the unmodified filename from the grf. Instead make it valid and unique.
- Fix: Off-by-one error in decoding of scStoreCompressed sprites. Though it worked in most cases :)

[gmyx]

Nice tool, it will make my documentation much simpler!

Would it be possible to add an option to remove the frames? I personally hate frames.

On to my real comments. While your tables are technically correct, you should code them up more explicitly. By this I mean:

• TH for the first row to properly define the row headers.
• using the 'id', 'scope' and 'headers' attributes
• All tables require a caption and a summary
• The summary that you provide would not be normally considered useful (think when it's on it's own - it should say the general content of the table

Other suggestions:

• Don't put any text after the closing body tag -> that is invalid code
• Use CSS for formating instead of <b> tag (you might want to consider using <h2> instead and style the h2. (also possible add a colon to more clearly separate the heading from it's content)
• Add a <h1> that matches the page title
• Put the sprite number in it's own column.

Sorry, but I'm a stick for well written HTML and CSS code. I can see great potential and I sure other will have suggestions to add! I may have more as well when I get more time to explore it.

[frosch]

Would it be possible to add an option to remove the frames?

Without frames I guess it will look the same as if you open "nfo.html" instead of "index.html". I used frames, so I can scroll the links independent from the content.

• TH for the first row to properly define the row headers.
• using the 'id', 'scope' and 'headers' attributes
• All tables require a caption and a summary
• The summary that you provide would not be normally considered useful (think when it's on it's own - it should say the general content of the table

I only added the summary tag because I was tired of filtering the warnings of htmltidy with grep. I don't think these attributes are useful at all. I do not even know where they are shown in my browser (firefox).

Don't put any text after the closing body tag -> that is invalid code

Where did I do that? I tested a lot of grfs and htmltidy never said anything.

[*]Use CSS for formating instead of <b> tag (you might want to consider using <h2> instead and style the h2. (also possible add a colon to more clearly separate the heading from it's content)
[*]Add a <h1> that matches the page title

Hmm, I wanted to keep it simple. But if you can provide me a short example of how it should look like, we will see

[*]Put the sprite number in it's own column.

There is a column for the sprite numbers. Though "subsprites" of Action1/5/A/11/12 are printed together with their "parentsprite".

[minime]

Action 12 and 13 are untested due to lack of grfs for testing.

For action 12 try unifont.grf. I even have a few other GRFs that contain more symbols, if that's necessary.

EDIT: I've also noticed that in case of UTF-8 strings (withing Action 4) you just dump the two bytes that encode the initial 'Þ' character in hex. It may be better to handle that differently.

EDIT2: Looks like UTF-8 and special character codes give you a bit of trouble. Try the GRF of Czech translation (download) - that contains a lot of strings to test it on.

And one last thing - Try decoding the Czech Railset and you'll find that the program fails to do so. It is a valid GRF, but it wasn't encoded by grfcodec.

[belugas]

Congratz to frosch.
I really like the output of it. Makes the whole thing easier to follow.

On a side note, I have to agree with frosch regarding the CSS use. It is better to keep it as simple as possible.

[AndersI]

Nice tool! Definitely helping in understanding a grf. I like the clickable links in VarAction2 and Action7/9, for example.

Some suggestions (all IMO, of course):

Drop the # sign on the sprite numbers - it only makes the number more difficult to read, and it takes longer to scan up- or downwards when looking for a certain line. Maybe left-justify the number to set it out a bit.

Use " only for real strings, use < and > for explanatory text - so, instead of:
Feature 0x04 "stations"
use
Feature 0x04 <stations>

Use different colors to distinguish different syntactical elements - strings, general numbers, ID:s, that would make it much easier to read.

I would like to have the possibility to see the plain NFO line(s) too - at least up to ?? bytes - as the first or second line in each cell.

Folding RealSprites in the contents bar would make it easier to get an overview. The contents bar also feels a bit empty, maybe there are some keywords (codes) that can be included to realize the difference between 120 RealSprite lines (for example). The name of the train/vehicle/house/station if possible.

Don't use ":=" unless there actually is an assignment, if you mean equality, use "=" or "=="

The "Date of introduction" as decimal number isn't very interesting, I certainly don't know when "0x4303 (17155)" is. Maybe it should be recalculated to year-month? There might be more numbers that need special care.

I concur to the suggestion of a standard CSS file, that would make it easier for me to set my favorite coloring, font style, size etc. I think it will in fact make the program simpler, as the CSS is a separate document, and the program doesn't have to know so much about formatting, only setting the display class for each 'element'.

Oh, and did I say Nice tool!?

So, why are you not involved with GrfMaker yet?

[gmyx]

Would it be possible to add an option to remove the frames?

Without frames I guess it will look the same as if you open "nfo.html" instead of "index.html". I used frames, so I can scroll the links independent from the content.

You right. Ignore me on that one.

• TH for the first row to properly define the row headers.
• using the 'id', 'scope' and 'headers' attributes
• All tables require a caption and a summary
• The summary that you provide would not be normally considered useful (think when it's on it's own - it should say the general content of the table

I only added the summary tag because I was tired of filtering the warnings of htmltidy with grep. I don't think these attributes are useful at all. I do not even know where they are shown in my browser (firefox).

You need the web developers toolbar, and there is a option under "Information" --> "Display Table Information". As for those attributes, it doesn't matter much for us here but they are part of the table specifications. At least put a TH so when its printed it puts the headings everywhere. I forgot to mention you should also use THEAD and TBODY, especially for those who would like to print so that the heading are on top of the page.

Don't put any text after the closing body tag -> that is invalid code

Where did I do that? I tested a lot of grfs and htmltidy never said anything.

"nfo.html" its at the bottom.

[*]Use CSS for formating instead of <b> tag (you might want to consider using <h2> instead and style the h2. (also possible add a colon to more clearly separate the heading from it's content)
[*]Add a <h1> that matches the page title

Hmm, I wanted to keep it simple. But if you can provide me a short example of how it should look like, we will see

Will do. It will take a few minutes. It will be a fully document table as well so you can see what I mean with the attributes.

[*]Put the sprite number in it's own column.

There is a column for the sprite numbers. Though "subsprites" of Action1/5/A/11/12 are printed together with their "parentsprite".

Quite right, I didn't look like it since there was no border.

Other observations: you shouldn't use the align attributes in tr and td, you should use css for that.

Edit: same goes for border and width on the table tag

[DaleStan]

Looks nice. Far better than the @@LOCATE I hacked into NFORenum a while back.

A few nitpicks, though:
"Random choise" -- "choice" is spelt with two 'c's and no 's'.
The plural of "aircraft" is "aircraft", not "aircrafts".

Also, Planeset uses vars 92, 9F, E2, and E6, which are not recognized by grf2html. This is, I assume, because you just used the variable descriptions from the wiki. svn://svn.ttdpatch.net/trunk/inc contains several files with complete listings of the 80+x variables. The savegame bible is less complete, but more descriptive.

I'm not sure how complete you intend to be, but recognizing at least var 92 would make it possible to recognize that decisions based on it are days-since-1920 decisions, possibly converting those into dates instead of bare numbers.

[gmyx]

Will do. It will take a few minutes. It will be a fully document table as well so you can see what I mean with the attributes.

I've created a simple file, see attachment. That is what I mean by attribute and tag usage. Notice all formating is in css. This allows for easy expansions. Note: IE has an issue with my css file. Well, really it has an issue with complying to standards.

This way you can style it any way you want without modifying the HTML code.

Edit: There may be a better way still by completely removing the base table. Just using H2s
Edit2: Included tableless version. Just h2 and h3 for structure, no table.

[belugas]

Sorry for the bad news, I've found a problem. When loading ECSTownw.grf beta 2, there is an access violation happening in nfoact0.pas, line 596, in procedure TAction0IndustryLayout.printHtml:

Code: Select all

layout[x, y] := i;

Looks line 213 causes the problem. I believe the 3th layout is the problem.

Code: Select all

             00 80 
             01 01 FE 8D 00 
             00 80

As you can see, it is only one tile, but with a 1,1 coordinate.

Code: Select all

setLength(layout, xMax - xMin + 1, yMax - yMin + 1);

defines, in this case, the array as been of 1*1 elements, thus at indice 0,0.
So, accessing it with index 1,1 just gets out of the boundaries.

How to solve this? I don't know, i'm too tired for that at the moment...

[frosch]

Thanks everybody for the feedback

I have uploaded a new version in the first post. The changelog is also there.

The UTF-8 support should work for most actions. However the ActionB built-in-messages are only in english, so they miss the 0xC3 0x9E, and UTF-8 will therefore not work in the <data> field.
For ActionC/10 comments UTF-8 is disabled. Don't know if that is always the best decision.
Further (if not using UTF-8) the latin1 characters in the range 0x9E..0xFF will not work yet. (They are shown as hex codes)

My long-time plans consist of:
1) Parse some Action0 properties with units, e.g dates.
2) Interpret TTDP string codes, i.e. replace them with some "<foobar>".
3) Centralize the HTML generation in one modul for easier adding of features regarding the output. After that perhaps some CSS.

Ok, now we are at the CSS topic:
I have to admit, that I like the idea of colored syntax highlighting very much. I guess this will require the use of CSS. But I will not overdo it, like gmyx suggests. (sorry, no offense)
Does someone else have a oppinion about gmyx's layout? I dislike the <h3> thingies, they do not align the values behind them like my tables do.

@AndersI
I agree that " is missplaced sometimes, but I am not sure if < and > is always a good replacement.
About the plain NFO code: I don't know where I should place it. What about an extra file with the plain NFO, that is linked (in a new tab) from the sprite numbers?
About folding the RealSprites: Perhaps a smaller font? Or print the "local sprite numbers" (e.g. Action1Set, Sprite of Set, Sprite of Action5/A/12, TTD SpriteNr for ActionA)?
About ":=": I am pretty sure I did not misuse it somewhere, and meant "assignment". If you disagree, you have to quote the exact text, where it is misused.

[gmyx]

3) Centralize the HTML generation in one modul for easier adding of features regarding the output. After that perhaps some CSS.

This sounds like a template - that is great. There are many ways that can be achieved.

Ok, now we are at the CSS topic:
I have to admit, that I like the idea of colored syntax highlighting very much. I guess this will require the use of CSS. But I will not overdo it, like gmyx suggests. (sorry, no offense)
Does someone else have a oppinion about gmyx's layout? I dislike the <h3> thingies, they do not align the values behind them like my tables do.

No offense taken, I'm an advocate for correct use of HTML and what I describe is XHTML to the letter in regards to tables. It does seem like overkill, but only because the browsers let us get away with too much. The best solution is a good template implementation so every one can generate the exact code they want. I prefer to use tables only when absolutely necessary and code to the published standards. That is why I used H1, H2 and H3 as they are logical sections in the document. You just need to style them up for the looks part. A perfect example is the CSS Zen Garden.

Question: What do you mean by not aligning? Most alignment issue can be fixed with some CSS.

Regardless, this is your product. Like I already said, I'm an advocate and in the end, you choose how to code your product.

[AndersI]

I agree that " is missplaced sometimes, but I am not sure if < and > is always a good replacement.

Maybe use {} for comments and [] for bit sets?

Code: Select all

#4    Action4 - Define custom texts
Feature    0x00 {Trains}
Language   0x1F [American, English, German, French, Spanish]
Text 0x00  "Ds (Electric, passenger)"

About the plain NFO code: I don't know where I should place it. What about an extra file with the plain NFO, that is linked (in a new tab) from the sprite numbers?

No, if it's to be useful at all, it should be almost at the top:

Code: Select all

#4    Action4 - Define custom texts
Code       04 00 1F 01 00 "Ds (Electric, passenger)" 00
Feature    0x00 {Trains}
Language   0x1F [American, English, German, French, Spanish]
Text 0x00  "Ds (Electric, passenger)"

with long code blocks truncated to end in "..."

About folding the RealSprites: Perhaps a smaller font? Or print the "local sprite numbers" (e.g. Action1Set, Sprite of Set, Sprite of Action5/A/12, TTD SpriteNr for ActionA)?

Actually, I think we could (mostly) manage completely without the "RealSprite" lines in the contents bar. As it is, the RealSprites occupies more room in the contents bar than the actual sprites take in the main window

About ":=": I am pretty sure I did not misuse it somewhere, and meant "assignment". If you disagree, you have to quote the exact text, where it is misused.

Maybe it is 'correct', but 'value' in VarAction2

Code: Select all

  value := ((Var41"Position in and length of chain of consecutive vehicles with same ID") shr 8)

doesn't really feel like an 'assignment' - it's more of a 'condition' that will be tested. The real 'assignment' in this case is the result of the VarAction2.

Another one: The Action0 property table is taking an awful lot of space. There's really no need for the " around the text, and two columns (or actually four) would squeeze the information into half the number of rows (maybe user selectable - screen widths do differ).

Another one: Could it be optional to have 'transparent blue' actually transparent in the sprites? That would make them easier to see. Maybe the sprite would need an extra one-pixel frame in that case? (but not necessarily, as we could run your program again and let it display the blue this time)

[FooBar]

2) Interpret TTDP string codes, i.e. replace them with some "<foobar>".

Judging by my username, that's a pretty good idea

[DaleStan]

However the ActionB built-in-messages are only in english

By that do you mean "in Grf2Html", or "in TTDPatch"? If the latter, then no, they're not. They are available by default in at least American, English, Spanish, French, and German, and they can be translated by translation GRFs, using action 4 and the appropriate F8xx IDs.

About ":=": I am pretty sure I did not misuse it somewhere, and meant "assignment". If you disagree, you have to quote the exact text, where it is misused.

Maybe it is 'correct', but 'value' in VarAction2

Code: Select all

  value := ((Var41"Position in and length of chain of consecutive vehicles with same ID") shr 8)

doesn't really feel like an 'assignment' - it's more of a 'condition' that will be tested. The real 'assignment' in this case is the result of the VarAction2.

It took me a while, but value is assigned to something, and then something else, and then something else, one time more than the count of operation bytes. (With operators 0E..10 being different, since they are.)
Then the decision is made on the final value of value.

Another one: The Action0 property table is taking an awful lot of space. There's really no need for the " around the text, and two columns (or actually four) would squeeze the information into half the number of rows (maybe user selectable - screen widths do differ).

Don't forget that it's possible to set properties for multiple IDs in one action 0. There's good reason not to make multiple columns for the property.

I like the formatting of recolor sprites. Really makes the signal stand out from the noise.

But in the reduction-of-noise department, would it be possible to write "(Var1A"always -1") and 0x00000020" as "0x00000020" instead? Or, even better, "0x20"?

[frosch]

@AndersI: Thanks, the { and } seem to match. Your other questions were answered correctly by DaleStan. I think these assignments are best suited for the Advanced VarAction2 and returning computed results. About your other suggestions: I think I will take a certain offer from Belugas.

Question: What do you mean by not aligning? Most alignment issue can be fixed with some CSS.

E.g. the Action8 in your suggestions: The values of "GrfVersion", "GrfID", "Name" and "Description" where previously in their own column, i.e. their left ends were aligned.

However the ActionB built-in-messages are only in english

By that do you mean "in Grf2Html", or "in TTDPatch"?

Yes I meant Grf2Html. I will not add the strings of all translations to Grf2Html. And I guess Grf2Html will never get the intelligence to unterstand an Action4 and then immediatelly use the string in the next ActionB.

[frosch]

New bug fix release in first post.

Thanks to orudge and belugas the source code is now available from svn.

[belugas]

Well... Thanks to you for such a great tool...
Pretty usefull in these times of newindustries debugging

[AndersI]

Thanks to orudge and belugas the source code is now available from svn.

That's great!

Although it's a bit disturbing that the revision number seems to apply to all projects in the repository. Suddenly GrfMaker was at revision 116 with no visible changes for 114-116!

Belugas: Is this a necessary effect of the SVN, or did you miss something when adding the new projects?

[belugas]

It is a normal behaviour, Andersi. The svn server knows only about the overall changes. He does not care about the branches/repos inside it.
The same happens on Open's svn server. A branch increments the revision number as well as a regular commit.
I understand the confusion but it's that or we use another svn server just for grf2html. Seems like an overkill to me.

Anyway, there are still logs. It's just an habit to take to look at them more carefully.

One way to make it less confusing is to prefix the commit log with the name of the project.
This is what OTTD do with anything that is not trunk.