Rendering bugs & small talk

The official forum for ZSNES documentation. Discuss future changes, mistakes, etc...
You can also join us on IRC at irc.freenode.net in #zsnes-docs.

Moderators: ZSNES Mods, ZSNES Doc Team

Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Rendering bugs & small talk

Post by Jipcy »

Please post all HTML rendering bugs in this topic.

Please try to view the offending page in at least two different browsers (one preferrably being standards-compliant, i.e. Firefox / Mozilla / Opera).

We do not include browser-specific hacks, so the bug might be there until the company fixes it.



Original Post:
Hey Clements, in the CHM file, the index needs to be updated. For example, the Movie Dumping section is not listed under Advanced Usage.

Also, "Files" and "Basic Usage" are missing from Readme. And, there was a slight change to the v800 changelog in History.
Last edited by Jipcy on Thu Nov 30, 2006 10:57 pm, edited 1 time in total.
Deathlike2
ZSNES Developer
ZSNES Developer
Posts: 6747
Joined: Tue Dec 28, 2004 6:47 am

Post by Deathlike2 »

The logos at the bottom also aren't consistant with the docs at the moment.
Continuing FF4 Research...
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

Yes, I know. I need to change the XHTML 1.1 to 1.0. And I'll look at the others at some point.
Clements
Randomness
Posts: 1172
Joined: Wed Jul 28, 2004 4:01 pm
Location: UK
Contact:

Post by Clements »

All fixed.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

Clements, the CHM file isn't quite right. There have been some recent CSS changes that might be the problem. Also, a number of the bookmarks under Games don't work. Also, just a heads up, Things To Know has been deleted from the Readme.
Clements
Randomness
Posts: 1172
Joined: Wed Jul 28, 2004 4:01 pm
Location: UK
Contact:

Post by Clements »

I'll try to fix those Wednesday or Thursday. As usual, your help is greatly appreciated.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

I'll be gone for Thanksgiving. I'll be back at school probably Saturday or Sunday, however I'm going to be pretty busy with school until the end of the semester (December 15th-ish).
Clements
Randomness
Posts: 1172
Joined: Wed Jul 28, 2004 4:01 pm
Location: UK
Contact:

Post by Clements »

Fixed the minor issues, and now the broken tables, which is a stylesheet issue.

- The stylesheet updates in r986 broke the tables in the CHM.
- The r985 stylesheets worked and showed the table lines etc.

From that, I worked out the exact problem. The CHM does not like the new shared.css file for whatever reason. I saw what you did with that, so copying the contents of shared.css into radio.css where it was originally fixes the problem and everything works perfectly. I've committed a CHM that fixes the tables for now.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

ASquire, nice work on all the txt updates. Did you notice/use the new plaintxt.css stylesheet? I made it to render to HTML docs somewhat like the TXT docs. You may find it useful. I might edit it some more later to make the HMTL docs look more like the TXT docs.
AspiringSquire
Born to Rule... Impatiently
Posts: 265
Joined: Wed Nov 17, 2004 8:21 pm
Location: Everywhere I want to be.
Contact:

Plain-Text HTML

Post by AspiringSquire »

Jipcy wrote:ASquire, nice work on all the txt updates.

Thanks. I appreciate your appreciation; updating the docs can be pretty time-consuming. By the way, I'd like to point out that it is especially helpful for me when you distinguish between updates to the content and changes to the markup, and even more so when those are done with separate commits.

Jipcy wrote:Did you notice/use the new plaintxt.css stylesheet? I made it to render to HTML docs somewhat like the TXT docs. You may find it useful. I might edit it some more later to make the HMTL docs look more like the TXT docs.

I did notice the plaintxt stylesheet; it's pretty nifty. For a moment I felt like my hand-made .txt files would be obsolete! Fortunately, I got over that. Auto-generated fixed-width text files may never quite compare with carefully constructed files done manually, but you have a good start to the plain-text version of the HTML. The main thing that doesn't yet conform to plain-text "standards" is that there are still bold and italicized parts. It looks good, though.

I haven't been using it to assist in updating; I still prefer the default stylesheet for that, and it's annoying to keep reselecting a non-default style every time I change to another page.
My NES palette - better colors with any emulator.

"the more you know, and the more you can do... the more you are."
- daniel bohman
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Re: Plain-Text HTML

Post by Jipcy »

AspiringSquire wrote:By the way, I'd like to point out that it is especially helpful for me when you distinguish between updates to the content and changes to the markup
Yes, at some point I realized that; I'll keep in mind to always do that.

and even more so when those are done with separate commits.
Do you mean that you would prefer if I committed all markup changes separately from all content changes? I'll do my best to do that from now on.

By the way, do you use the DIFF function in TortoiseSVN? When I see that you or someone else updates an html file, I pretty much DIFF everyone with the revision before, and look at each change.

My point is, sometimes I make many very minor changes to a file, and it would be silly to list them all out in the commit comment. So, my question is, would you prefer briefer comments (because you're going to DIFF the file anyway) or lengthier comments (because you'd rather not have to DIFF)?

Fortunately, I got over that.
That's good. My stylesheet isn't intended to replace your files, but more so to assist in txt/html conversion.

I am interested to know your general process of converting the html docs to the txt docs. Do you have some way to automatically break the lines of text at a specific width? Or do you have to do all of that manually? If manually, then, my god, I would never have the patience for that.

it's annoying to keep reselecting a non-default style every time I change to another page.
I agree. The alternate stylesheets are still somewhat just for experiment.
AspiringSquire
Born to Rule... Impatiently
Posts: 265
Joined: Wed Nov 17, 2004 8:21 pm
Location: Everywhere I want to be.
Contact:

Converting the docs to text from HTML. Committing comments.

Post by AspiringSquire »

Jipcy wrote:I am interested to know your general process of converting the html docs to the txt docs. Do you have some way to automatically break the lines of text at a specific width? Or do you have to do all of that manually? If manually, then, my god, I would never have the patience for that.

Well, once I'm fully committed to doing something, I have an enormous amount of patience. I do have help from the editor, metapad, so I'm only doing it semi-manually.

First of all, I made sure to adjust the window dimensions (of metapad) to display exactly 80 characters per line. Then, with Word Wrap disabled, I can always know when one or more lines exceed the intended limit because the horizontal scrollbar will be active. A feature in metapad allows auto-indenting of text when you hit Enter (matching the indentation of the line above), so I don't have to insert all of the spaces manually, either; it's just a matter of seeking to the end of a nearby appropriately-limited line, moving the cursor up or down, and inserting a return at the end of the last word that fits on a given line. There's also a command to "Strip Trailing Whitespace" for selected text, which is very handy for removing the excess that you otherwise don't notice.

I don't always copy and paste entire paragraphs from the HTML; if most of a paragraph remains the same, I often paste the changed part and shift the following lines as necessary.

What can make synchronization updates difficult (or just take longer) is trying to find all of the changes that actually affect the txt docs. I do use the DIFF tool, but it isn't perfect, and with dozens of lines updated for the markup and content, it can still take a while to sift through them, since one line of HTML generally equates to several lines of text content. This is why I would prefer markup and content commits to be separate from each other.

Jipcy wrote:My point is, sometimes I make many very minor changes to a file, and it would be silly to list them all out in the commit comment. So, my question is, would you prefer briefer comments (because you're going to DIFF the file anyway) or lengthier comments (because you'd rather not have to DIFF)?

As I see it, commits should be informative enough that someone would get the general idea of what you did, and where (by specifying sections or particular items, as appropriate), so that when someone DIFFs the revision, they know what types of changes to expect. This means that the degree (or type) of specificity may vary depending on the task.

For a documentation-wide change such as altering some capitalization (e.g. VSync), I think it's appropriate to say what words are being changed, but it doesn't need to include the exact locations, since SVN can tell you that. For description updates, when you change a phrase or two, it would be sufficient to say that you did (minor) rewording/revision for an item or within a section; if you have many such small changes throughout a page, you could broadly state that there are several minor revisions/additions in a given page, but if some are much more significant than others, it may make sense to note them.

I don't want to be imposing a bunch of restrictions on you; hopefully you can follow/understand the spirit of my feelings on this from what I've said.
My NES palette - better colors with any emulator.

"the more you know, and the more you can do... the more you are."
- daniel bohman
Nach
ZSNES Developer
ZSNES Developer
Posts: 3903
Joined: Tue Jul 27, 2004 10:54 pm
Location: Solar powered park bench
Contact:

Re: Converting the docs to text from HTML. Committing commen

Post by Nach »

AspiringSquire wrote:There's also a command to "Strip Trailing Whitespace" for selected text, which is very handy for removing the excess that you otherwise don't notice.

The ZSNES toolkit includes a program called minwhite (zsnes/trunks/src/tools/minwhite.cpp) which trims any trailing whitespace off of every single line in all *.asm, *.inc, *.mac, *.h, *.c, *.cpp, *.psr files in the current directory and all sub directories.

Since it's useful for this too I whipped up a docs version, which strips *.htm, *.html, *.css, *.js, *.txt. It's here: http://www.geocities.com/joecool22us/minwhite-docs.zip

Note, a Geocities link, so copy and paste or double enter or whatever to fool referer.
May 9 2007 - NSRT 3.4, now with lots of hashing and even more accurate information! Go download it.
_____________
Insane Coding
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

AspiringSquire, I forgot to put it in the commit message, but in Readme.txt, I made the percentages in the special chip tables look (in my opinion) better.

I also edited the txt docs with a few wording changes I made to the HTML docs.
AspiringSquire
Born to Rule... Impatiently
Posts: 265
Joined: Wed Nov 17, 2004 8:21 pm
Location: Everywhere I want to be.
Contact:

No Removal of Information

Post by AspiringSquire »

Jipcy wrote:AspiringSquire, I forgot to put it in the commit message, but in Readme.txt, I made the percentages in the special chip tables look (in my opinion) better.

I suppose it does make it easier to compare the percentages that way; it looks good.

Jipcy wrote:I also edited the txt docs with a few wording changes I made to the HTML docs.

This is okay, mostly. I don't approve of the complete removal of information, as you have done with the paths for Same Game and SD Gundam G-Next base ROMs. You said that "People can just specify the full path all the time unless they know better." But how would they know without it being stated in the docs?
My NES palette - better colors with any emulator.

"the more you know, and the more you can do... the more you are."
- daniel bohman
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Re: No Removal of Information

Post by Jipcy »

AspiringSquire wrote:
Jipcy wrote:I also edited the txt docs with a few wording changes I made to the HTML docs.

This is okay, mostly. I don't approve of the complete removal of information, as you have done with the paths for Same Game and SD Gundam G-Next base ROMs. You said that "People can just specify the full path all the time unless they know better." But how would they know without it being stated in the docs?

I'll add back the info in a better way later, then.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

Deathlike, what do the SVN properties do? I noticed you updated a bunch of them in the zsnes-docs repository. What were they before and what did you change them to?

Also, I believe one of Nach's line ending and white space trimming tools changes line endings to Unix style rather than Windows style.

I think we need to decide what encoding and line endings the docs should use. UTF-8 isn't the greatest because some text editors don't handle it so well. I don't know about Unix vs. Windows line endings, though.
Nach
ZSNES Developer
ZSNES Developer
Posts: 3903
Joined: Tue Jul 27, 2004 10:54 pm
Location: Solar powered park bench
Contact:

Post by Nach »

My whitespace cleaning tools convert to unix style if ran in unix.
The SVN properties make it unix style from unix and DOS style from Windows.
As for the docs, distribution should be Windows style for DOS/Windows, I forgot to convert when I packaged 1.50, hopefully I'll remember for next version.
Under no circumstances should unix line endings be forced on Windows or vica versa.
May 9 2007 - NSRT 3.4, now with lots of hashing and even more accurate information! Go download it.
_____________
Insane Coding
Deathlike2
ZSNES Developer
ZSNES Developer
Posts: 6747
Joined: Tue Dec 28, 2004 6:47 am

Post by Deathlike2 »

Jipcy wrote:Deathlike, what do the SVN properties do? I noticed you updated a bunch of them in the zsnes-docs repository. What were they before and what did you change them to?


Most of them didn't have properties (the html/txt files). There are two properties I did set.. one for keywords (probably not as useful for most). Also, one for "style". Native means that when someone using different OSes obtain the docs, they will be represented in the proper format. I find this extremely useful especially because it drives me nuts that most of the added files by Nach is in unix format. Adding these properties translates them properly so it doesn't look out of whack in Notepad. So, whoever works on the docs in Linux wouldn't hurt the progress of someone working in Windows, and vice versa.

The only other tweak is changing whatever the default properties for image (png) files (application/octet-stream == binary I think, you can find that in the chm) and changed it to image/png which is the appropriate type for such files.

I think we need to decide what encoding and line endings the docs should use. UTF-8 isn't the greatest because some text editors don't handle it so well. I don't know about Unix vs. Windows line endings, though.


Well, meta/default.htm is the most annoying file for metapad, to say the least.
Continuing FF4 Research...
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

Deathlike2 wrote:
I think we need to decide what encoding and line endings the docs should use. UTF-8 isn't the greatest because some text editors don't handle it so well. I don't know about Unix vs. Windows line endings, though.


Well, meta/default.htm is the most annoying file for metapad, to say the least.

I haven't updated that file in ages. It's in no way current. Change it as you like.

I recommend at least *trying* Notepad++. It an handle several encodings and line endings.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

xamenus, can you please delete

Code: Select all

/home/groups/z/zs/zsnes-docs/htdocs/docs/wip/images/
on the shell server? It doesn't have group permissions.

As far as I know, I set permissions on all the files I uploaded so that other people could delete them as necessary. Nach, do you know anything about this? What should the permissions be set to (I know we talked about this before)?
Nach
ZSNES Developer
ZSNES Developer
Posts: 3903
Joined: Tue Jul 27, 2004 10:54 pm
Location: Solar powered park bench
Contact:

Post by Nach »

To delete a file, it's parent directory should have the group be zsnes-docs, and it's group write permission should be set.
If you're using octal based permissions, the parent directory should have a 2 bit set in it's middle digit.

If you happen to be using SSH, you can type:
chmod g+w /path/to/directory
To make it group writable.
May 9 2007 - NSRT 3.4, now with lots of hashing and even more accurate information! Go download it.
_____________
Insane Coding
xamenus
Veteran
Posts: 907
Joined: Fri Jul 30, 2004 12:26 am

Post by xamenus »

Jipcy wrote:xamenus, can you please delete

Code: Select all

/home/groups/z/zs/zsnes-docs/htdocs/docs/wip/images/
on the shell server? It doesn't have group permissions.
It's not letting me delete it either. In fact, when I try to access the 'wip' folder, I get an error message saying that the server returned an empty listing for the directory. So I can't even see the 'images' folder. I can't change the 'wip' folder's permissions either, though write permissions for the group look to be enabled.

I'm using WinSCP.
Jipcy
Veteran
Posts: 768
Joined: Thu Feb 03, 2005 8:18 pm
Contact:

Post by Jipcy »

Can you try logging in with FileZilla+Pageant or something? I can see the folder in FileZilla.
xamenus
Veteran
Posts: 907
Joined: Fri Jul 30, 2004 12:26 am

Post by xamenus »

Jipcy wrote:Can you try logging in with FileZilla+Pageant or something? I can see the folder in FileZilla.
No luck. Still the same problem.
Post Reply