ok, some more suggestions (sorry to bother). at least these won't change the design.


Suggestion1: I found out that 'operator precedence' is missing in the doc. Shouldn't there be a table somewhere? It would be helpful. For those who don't know, here's it (the top-most operators have the highest precedence, and those separated with commas have the same precedence):

not, -
shl, shr
and, or, xor
mod
*, /
+, -

The - in red represents the unary '-' operator. If there are other operators I missed, please correct me. I think a table like that would be helpful, and would make the doc more complete

sure, the table should also contain the associativity of these operators. From my knowledge, only not and the unary - are right-associative. The others are all left-associative.

So, what do you think? or is this an old question?


Suggestion2: How about more descriptive doc for the 'match' directive? For example, in the doc it's not very clear that you can do something like:

from the doc, it's not really explicit this 'trick', which is VEERY useful in many situations. Maybe add something from this thread to the doc?

Ad1: http://flatassembler.net/docs.php?article=manual#_1.4
Ad2: the documentation contains just general syntax description with a few examples, the detailed explanation of applications I plan to put in the "Understanding fasm" auxiliary article. Follow http://board.flatassembler.net/topic.php?t=4638 to see what I mean (with another reference to Chapter 1).

Here's a really silly question: what is the big advantage of using PDF format for, well, anything?

The advantages are similar to PostScript, but PDF offers better compression. And hyperlinks.

really, don't you think HTML would work better? Docs are anyway in archive, and i believe zipped pure text has better compression than PDF. Also it can be browsed faster, at least i believe, than PDF with sloppy overbloated acrobat reader.

I know it's not printable, but how many people print it?

HTML allows too much loose interpretation from the client side, it's not much a publishing format really.
And for a long time I had a computer with PDF reader but no HTML reader at all (yeah, Win95; but also just DOS*). HTML version is available online (just like it should) and that's enough in my opinion.

* Found that it's still downloadable: http://www.haitjema.com/acrobatdos.html However you cannot read FASM.PDF with Acrobat 1.0, as it uses PDF 1.4, for better compression.

PDF has one big advantage for me - table of contents on the left. Even the huge Intel manuals are usable thanks to this feature.

Does the FASM documentation really need "strict" interpretation, though?

IMHO, the ideal format would be MS CHM - very decent for searching, indexing et cetera. Perhaps using some meta-format that can be exported to chm, html, pdf would be *the* solution, but might take a fair amount of work.

The fasm documentation overall doesn't need it, but I like to have it in the three forms - clean text (for DOS nostalgia reasons), browsable form online and printable form in some nice DTP-like format (as actually the most "serious" form of them).

Understandable - and it *is* hard to beat PDF for print. Are you prepearing each format manually, or do you have some "metaformat"?

well, having CHM surely would be nice. THAT would be the format i will be using.

i think there was some older version in chm format...

My "metaformat" is LaTeX (what would you expect from mathematician? ). However I'm do some of the conversions manually, as I'm not satisfied with automated ones.

Hmm, unless it was a wet feverish dream ^_^, I think I saw some way of getting CHM output from LaTeX. And even if it was a dream, if you get HTML from LaTeX, it should certainly be possible to do CHM somehow.

On a sidenote, I want to look into LyX soon. I find it a bit tedious writing TeX by hand, especially when spellchecking. LyX does seem pretty interesting.

Well, I just ask because of several reasons. Google's recent acquisition of Writely hints that exporting to PDF will cost money, but the standard format would be HTML. PDF seems to be more of a proprietary format than not (i.e., can't convert some PDFs to text because "the author doesn't want that"). Plus, I've tried Acrobat for DOS (long time ago), and it didn't work with the files I had. And, recently when I updated Acrobat Reader for Windows it was HUGE (Emacs, eat your heart out)! Besides, you can search with any standard text viewer, so why do you need it in PDF or CHM just to do that?!

I'm not saying FASM should use something different, it's your call. But, I prefer plain text personally. Several programs use their own intermediate format (NASM, Allegro, etc., IIRC). And I think NASM's former author (Simon) has come up with another, "better" documentation format.

GNU texinfo ("teKinfo") seems like a semi-good compromise, in my opinion, but I'm sure there are problems there too. Bah!

P.S. I never print out documentation. In fact, my "new" printer is on the fritz (blasted things never work consistently).

sorry for that
I guess I didn't really see it as 'precedence', since the table uses the priority.. probably my mind just didn't analyzed it enough
ps: and the unary '-' is missing. Shouldn't it be there?


Aha, I get it now.


EDIT: and about the PDF thingy, well, I gotta say I don't really like it, because it's a bit bloated (around 400KB for the documentation...). I don't really have a format to recommend, and it's your choice.

If it wasn't PDF, I would go for the pure PostScript. But it would be even larger then (and you wouldn't like DVI, would you? ).

PS. As for the unary "-", I've corrected it to have the same precedence as substraction, so "-2 and 3" gives the same result as "0-2 and 3".

If you'd rather avoid Adobe's Acrobat bloat but still read PDFs, try Foxit Reader (Win95+, 1.5 MB but Linux version exists too).

If you want a good small web browser, try OffByOne (Win95+, 1.2 MB).