flat assembler
Message board for the users of flat assembler.

Index > Main > Suggestions for documentation...

Author
Thread Post new topic Reply to topic
Borsuc



Joined: 29 Dec 2005
Posts: 2466
Location: Bucharest, Romania
Borsuc
ok, some more suggestions (sorry to bother). Smile 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 Wink

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:

Code:
match any + remaining, 28 4 3 2 1 sc + 83 2 1 4
{
  ; 'any' is now "28 4 3 2 1 sc"
  ; 'remaining' is "83 2 1 4"
}    
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?
Post 01 May 2006, 12:09
View user's profile Send private message Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
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).
Post 04 May 2006, 07:24
View user's profile Send private message Visit poster's website Reply with quote
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
Here's a really silly question: what is the big advantage of using PDF format for, well, anything?
Post 05 May 2006, 04:55
View user's profile Send private message Visit poster's website Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
The advantages are similar to PostScript, but PDF offers better compression. And hyperlinks.
Post 05 May 2006, 07:56
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
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?
Post 05 May 2006, 08:37
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
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.
Post 05 May 2006, 09:09
View user's profile Send private message Visit poster's website Reply with quote
MazeGen



Joined: 06 Oct 2003
Posts: 975
Location: Czechoslovakia
MazeGen
PDF has one big advantage for me - table of contents on the left. Even the huge Intel manuals are usable thanks to this feature.
Post 05 May 2006, 09:23
View user's profile Send private message Visit poster's website Reply with quote
f0dder



Joined: 19 Feb 2004
Posts: 3170
Location: Denmark
f0dder
Quote:

HTML allows too much loose interpretation from the client side, it's not much a publishing format really.

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.
Post 05 May 2006, 10:49
View user's profile Send private message Visit poster's website Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
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).
Post 05 May 2006, 10:58
View user's profile Send private message Visit poster's website Reply with quote
f0dder



Joined: 19 Feb 2004
Posts: 3170
Location: Denmark
f0dder
Tomasz Grysztar wrote:
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"?

_________________
Image - carpe noctem
Post 05 May 2006, 11:01
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
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...
Post 05 May 2006, 11:18
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
My "metaformat" is LaTeX (what would you expect from mathematician? Wink). However I'm do some of the conversions manually, as I'm not satisfied with automated ones.
Post 05 May 2006, 11:20
View user's profile Send private message Visit poster's website Reply with quote
f0dder



Joined: 19 Feb 2004
Posts: 3170
Location: Denmark
f0dder
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.
Post 05 May 2006, 11:31
View user's profile Send private message Visit poster's website Reply with quote
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
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).
Post 05 May 2006, 16:57
View user's profile Send private message Visit poster's website Reply with quote
Borsuc



Joined: 29 Dec 2005
Posts: 2466
Location: Bucharest, Romania
Borsuc
sorry for that Embarassed
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 Smile
ps: and the unary '-' is missing. Shouldn't it be there?


Tomasz Grysztar wrote:
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).
Aha, I get it now. Smile


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. Smile
Post 05 May 2006, 17:12
View user's profile Send private message Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
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? Wink).
Post 05 May 2006, 18:26
View user's profile Send private message Visit poster's website Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 7718
Location: Kraków, Poland
Tomasz Grysztar
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".
Post 06 May 2006, 11:29
View user's profile Send private message Visit poster's website Reply with quote
rugxulo



Joined: 09 Aug 2005
Posts: 2341
Location: Usono (aka, USA)
rugxulo
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).
Post 27 Sep 2006, 03:36
View user's profile Send private message Visit poster's website Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum


Copyright © 1999-2020, Tomasz Grysztar.

Powered by rwasa.