flat assembler
Message board for the users of flat assembler.
 Home   FAQ   Search   Register 
 Profile   Log in to check your private messages   Log in 
flat assembler > Main > FASM Programmer's Manual, english articles.

Author
Thread Post new topic Reply to topic
jkhjklhgl



Joined: 04 Mar 2016
Posts: 9
FASM Programmer's Manual, english articles.
Why are so many occurrences of "a" and "the" missing or in the wrong places in the manual? It makes it much harder to read.
Post 20 Mar 2016, 16:26
View user's profile Send private message Reply with quote
idle



Joined: 06 Jan 2011
Posts: 341
Location: ukraina
those are implied, lack of commas - i would agree
Post 20 Mar 2016, 16:41
View user's profile Send private message Send e-mail Reply with quote
l_inc



Joined: 23 Oct 2009
Posts: 875
jkhjklhgl
Totally agree with you. The manuals need a good review, but I must say, the author does not incorporate all the suggested changes (even grammatical), so sometimes you'd need to be quite convincing in a discussion to make your fixes get accepted.

_________________
Faith is a superposition of knowledge and fallacy
Post 20 Mar 2016, 17:39
View user's profile Send private message Reply with quote
revolution
When all else fails, read the source


Joined: 24 Aug 2004
Posts: 14928
Location: 6EQUJ5
Concentrate on the content, not the delivery method.

Would you rather have a beautiful perfectly grammatical document that doesn't have enough details to explain what you want, or a plain slightly ungrammatical document that has all the finer details needed to get your work completed?
Post 20 Mar 2016, 17:47
View user's profile Send private message Visit poster's website Reply with quote
l_inc



Joined: 23 Oct 2009
Posts: 875
revolution
It depends. There were sentences that I was unable to understand for months just because they were composed inappropriately.

_________________
Faith is a superposition of knowledge and fallacy
Post 20 Mar 2016, 17:50
View user's profile Send private message Reply with quote
Trinitek



Joined: 06 Nov 2011
Posts: 256
I agree with l_inc. Speaking of "documents that don't have enough details to explain what you want," I feel as if a few of the directive descriptions are so short and cryptic as to be of no more use than to simply say, "this directive exists." A well written manual shouldn't have to fully rely on example files to demonstrate how to use a particular feature.
Post 20 Mar 2016, 19:39
View user's profile Send private message Reply with quote
revolution
When all else fails, read the source


Joined: 24 Aug 2004
Posts: 14928
Location: 6EQUJ5

Trinitek wrote:
Speaking of "documents that don't have enough details to explain what you want," I feel as if a few of the directive descriptions are so short and cryptic as to be of no more use than to simply say, "this directive exists."

That addresses the content, and should be fixed if time allows. Maybe you could help by pointing out what directive explanation(s) you are referring to.
Post 20 Mar 2016, 19:43
View user's profile Send private message Visit poster's website Reply with quote
l_inc



Joined: 23 Oct 2009
Posts: 875
revolution

Quote:
That addresses the content


Grammatical correctness by itself addresses the content to a large extent. Speaking about the articles, the subject of the topic, the definite article is a way to tell a reader that the referred entity should be known or identifiable by the reader. If I see the definite article and don't know what exact individual entity the noun refers to, then I get confused and think I probably missed something before, and then I have to reread a couple of previous paragraphs. And even this is a better case. It could become worse, if there can be found an entity that the noun could be incorrectly attributed to. This is exhausting and I don't understand why you offer those alternatives. Like do you prefer lifetime slavery or your hand to be cut off? Are grammatical correctness and content comprehensiveness mutually exclusive?

I don't mean good quality of a product we don't even pay for may be demanded, but I find it perfectly OK for the community to take part in facilitation of its improvement by reporting or fixing both content shortcomings and grammatical mistakes. From what you say it's like only the former kind of defects is acceptable to report.

_________________
Faith is a superposition of knowledge and fallacy
Post 20 Mar 2016, 21:17
View user's profile Send private message Reply with quote
fasmnewbie



Joined: 01 Mar 2011
Posts: 399
FASM manual is written in technical writing language and format, similar to Intel Software Manual. You don't read a manual like reading a book that has a clear flows, starting point and end point. A manual style of writing enable people to start or to jump from any point to another point. Manual is a free-flowing material and it doesn't need to follow a strict grammatical or chronological order.

There are reasons why people still need assembly programming books even when the Intel manuals are widely available in volumes and for free too. People need to consult other source and since FASM don't have a book, yet, you can ask for clarifications from this forum.

The C language is even far worse and more cryptic than English language, so if FASM manual is missing an "a" or two, I think I can live with that.
Post 21 Mar 2016, 01:14
View user's profile Send private message Visit poster's website Reply with quote
fasmnewbie



Joined: 01 Mar 2011
Posts: 399
Sometimes, we just need to look at the bigger picture to see things more clearly.
Post 21 Mar 2016, 01:30
View user's profile Send private message Visit poster's website Reply with quote
Tomasz Grysztar
Assembly Artist


Joined: 16 Jun 2003
Posts: 6436
Location: Kraków, Poland
This is a real problem, not only because manual could sometimes be misunderstood, but also because this may create an impression of poor quality that would be associated with the content of the website and then fasm itself.

I've been aware that the manual needs editing, but I did not feel competent to do it myself and I did not know anybody that would be willing to do such large work as correcting the entire website.

And to my further embarrassment I had lost an e-mail with an effort to help I received years ago. Someone wrote to me with a list of corrections to fasm's manual and I was really grateful and wanted to apply these corrections when I have more time. But when I finally found some spare time to do that, I realized that the e-mail is nowhere to be found. I honestly don't know what happened to it and I don't even know who was the author. But the fact that fasm's manual is still in a form of the initial draft is all my fault.
Post 21 Mar 2016, 11:16
View user's profile Send private message Visit poster's website Reply with quote
DOS386



Joined: 08 Dec 2006
Posts: 1907
> Why are so many occurrences of "a" and "the" missing or in the wrong places in the manual? It makes it much harder to read.

I consider this problem as minor, the definite and undefinite articles are a problematic feature of the language anyway, and the "the" is sometimes being ridiculously overused ("THE END").

BUG:

Quote:
This is instruction has no operands.



So why not create a sticky thread "ERRATA about FASM's included documentation and website" ?
Post 21 Mar 2016, 12:14
View user's profile Send private message Reply with quote
l_inc



Joined: 23 Oct 2009
Posts: 875
DOS386

Quote:
the definite and undefinite articles are a problematic feature of the language anyway, and the "the" is sometimes being ridiculously overused ("THE END").


I'm not sure in what way the articles are problematic, but your "THE END" example does not show any problem or an overuse. This "the" has very clear semantics. It tells that the end being talked about is uniquely identifiable: there was no end before, and there will be no other end later, which also directly implies there can be no continuation (of whatever the end refers to) and no way back. I speak languages that don't have articles on a daily basis and this lack leads to (mostly minor) misunderstandings regularly. Fasm manual is overloaded with these problems. The total number of sentences in the manual is very probably lower than the number of misuses of the articles.

The quotation you provided in turn demonstrates a minor problem, because it's easily ruled out just by reading this single short sentence, and hence cannot lead to confusion.

_________________
Faith is a superposition of knowledge and fallacy
Post 21 Mar 2016, 13:20
View user's profile Send private message Reply with quote
AsmGuru62



Joined: 28 Jan 2004
Posts: 1385
Location: Toronto, Canada
I also found the manual slightly harder to read than other manuals.
Especially, the case of text flowing with no paragraphs in proper places.
So, lets help Tomasz (and community) to fix the manual.
Anyone?..
Post 21 Mar 2016, 14:33
View user's profile Send private message Send e-mail Reply with quote
Trinitek



Joined: 06 Nov 2011
Posts: 256
Perhaps it would be easier to collaborate on a better manual if it were in a wiki format.
Post 21 Mar 2016, 15:25
View user's profile Send private message 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


Powered by phpBB © 2001-2005 phpBB Group.

Main index   Download   Documentation   Examples   Message board
Copyright © 2004-2016, Tomasz Grysztar.