Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[MadAngus]

Browsed through the files you sent me. This is exactly what I had in mind, perfect. Yet again great work.

Page number bookmarks:
I wouldn't bother with hyperlinks on these if there is only one page reference. If the function has multiple page references such as "ThisFunction........18, 38" then, at least the subsequent number(s), i.e. '38', would obviously need a hyperlink.


Blank pages:
I think your following the same standard as I am for this. For new Sections/Chapters the first page should always land on the right hand page (odd numbered page), blank pages added if need be to force this. Are you following this method?


Credits:
For credits etc, You should use your real name for credit's as you should be billed as "Edited by 'your-name'" unless you prefer "Edited by bruceuncle". "Written by..." should be the original authors/editors.

Note, for the first release I do not get credited.

For the resource kit release "Edited by 'your-name'" will be displayed on the front cover artwork, I will be lower billed on the inside credit's page as "Typesetting by 'my-name'".


OpenOffice rtf:
Opens the rtf document without complaints.
All bookmarks, tables and hyperlinks recognised.
All hyperlinks function correctly.
I do loose the leaders in the contents and Index, but this is not something to worry about. A couple of edits to the styles and their fixed, a trivial matter.
[Edit 23/03/2012] As a result there should be no need to provide an ODT version of this, I should be fine working from the rtf version.

The instruction formats, layout, formatting etc, are as I have said, exactly what I had in mind.


A couple of trivial points:
Could the alphabetical index letters A,B,C... etc. be left aligned and in Bold, no underline.
Also for your release, when you are done, I'm fine with the title as is. However, for release with the Resource Kit I would prefer to title it as the "Programmer's Quick Reference".

Well done, and thanks again for the work your doing.

[bruceuncle]

If the function has multiple page references such as "ThisFunction........18, 38" then, at least the subsequent number(s), i.e. '38', would obviously need a hyperlink.

I haven't catered for multiple page references as I personally hate having to go though multiple pages to find what I'm looking for.  Each index will only ever be one page (for this reference work).  The topics are basically one instruction each and any qualification will be in the text part of the index.  Eg.  The "Left$ (Statement)" and "Left$ (Function)" entries in the sample.  For some of the more AMOS-specific instructions, where the instruction type alone is insufficient, the qualificaton will be in the topic name itself.  Eg. All Interface, Menu and AMAL instructions will have that qualification after their name.  And any other conflicts will be handled in a similar fashion.  If this does prove to be a problem (none that I can see from browsing the work-yet-to-be-done) then hyperlinks are a piece of cake to add.  All the RTF formatting definitions are contained in a single configuration object with nothing hard-coded in the RTF Writer itself.

OpenOffice rtf:
Opens the rtf document without complaints.
All bookmarks, tables and hyperlinks recognised.
All hyperlinks function correctly.
I do loose the leaders in the contents and Index, but this is not something to worry about. A couple of edits to the styles and their fixed, a trivial matter.
[Edit 23/03/2012] As a result there should be no need to provide an ODT version of this, I should be fine working from the rtf version.

Great.  That solves one problem with cross-platform portability.  The RTF as output by my writer should be version 1.5.  However, as I have to paginate in Word 2010 for the final result, the RTF after that will be version 1.9.  In theory ( ) anything an RTF reader doesn't understand should not be a problem as it should just be skipped.  But, I'll send you a sample after Word has had its claws into the pudding.  Word adds a whole heap (mountain?) of RTF in its save format, including Orifice Themes in hex format - file size blows out enormously!.   So please check it out in OpenOffice to see if it still behaves itself.

I've also noticed that Word 2010 changes the layout slightly (but enough to wreck pagination) if I save in *.docx or *.doc formats.  So much for Messysoft's compatibility promises.

In practice though, does it really matter?  I would have thought a release in PDF would suit most requirements.  And the data in the database is the grist for the mill for use in other applications.  What do you think?

A couple of trivial points:
Could the alphabetical index letters A,B,C... etc. be left aligned and in Bold, no underline.
Also for your release, when you are done, I'm fine with the title as is. However, for release with the Resource Kit I would prefer to title it as the "Programmer's Quick Reference".

No problem.  Just a quick change to the configuration object.

Thanks for the feedback.  Very much appreciated.  Now on with the show...

Reality check!  Editing the rest of the info will take some considerable time.  So I don't expect the final product to be ready for a matter of months, not weeks.  Much will depend on whether I get any other contract work this year (hopefully not as I really want to retire) and the extreme weather we're getting here.  I haven't even attempted a timeline as I always was a hopeless project manager.  But gut feel says "Some time this year" 

BTW.  That was 30 centimetres not 30 feet!   

[MadAngus]

In practice though, does it really matter?  I would have thought a release in PDF would suit most requirements.  And the data in the database is the grist for the mill for use in other applications.  What do you think?

For general release, PDF will be all that is required. For myself the final rtf would be needed. The database tables would also be handy to have (if you are releasing them) I could use those more or less as is for the MySQL/PHP online version. That is just the tables, not the code.

Reality check!  Editing the rest of the info will take some considerable time.  So I don't expect the final product to be ready for a matter of months, not weeks.

Valid point, applies to all parts of this project, it's ready when it's ready.

[bruceuncle]

The database tables would also be handy to have (if you are releasing them) I could use those more or less as is for the MySQL/PHP online version. That is just the tables, not the code.

No problem.  That's why I'm keeping all the docs text in the database - you can plonk whatever writer you want on it to produce whatever format output you require.  I just plug my writer into it and *.rtf pops out.  Same could be done with just about any format you want to output - just build a writer for it.

Back to the 'real' work...

[bruceuncle]

I really should make these monthly or fortnightly updates.  This one could be summed up as "Plod, plod, plod..."   

Lots still to do.  Just a matter of knocking off a few more instructions each session.

A few changes to the format:

• I didn't like the rather messy way I was handling multiple definitions for the same instruction keyword.  So they now take up a separate entry each.  They now match the index entries by appending the instruction type (see Left$ example from a couple of posts back).
• The original list of instruction type names has been expanded to:
  
  • Command - Causes something to happen but uses no Parameters.
  • Statement - A Command that uses Parameters.
  • Function - Returns a value and may use Parameters.
  • Structure - A program flow control element (name comes from the original AMOS Manual).
  • Operator - An element that combines values in a maths or logical operation.
• Other document element names have been expanded to:
  
  • Parameters - Expressions supplied to a Statement or Function.
  • Conditions - Expressions applied to a set of Structure elements.
  • Return Value - What a Function returns.
  • Statements - Program Statements that take part in a set of Structure elements.
  • Information - Ad hoc information sections relevant to a set of elements.

The only name I'm not happy with is "Structure".    The original manual uses this as the name for program flow control elements (eg. If...Then...Else...End If, Do...Loop, etc.).

The document layout means that these names need to be fairly short.  So "Program Flow Control" is not an option as an alternative.  Anyone got any other ideas?  Or should I just stick with "Structure"?

Any ideas welcome.

[MadAngus]

"Structure" to me implies some form of data set, structures (struct) in C++, Types in VB etc. However the only alternative I can come up with is "Conditional" i.e. A Conditional element:

Conditional - An element that must be qualified before proceeding.

[bruceuncle]

Yeah, "Structure" implies the same to me which is why I queried it.  Conditional doesn't really do the trick either as, for example, Pop, Gosub and Goto don't have one!  And it clashes a bit too much with the "Conditions" title in the syntax explanations.

As a definition, the instructions involved are any that change program flow from top-to-bottom sequence.

Ideal would be "Program Flow Control".  The nearest to that that makes sense is "Flow Control" - which doesn't quite fit in the 1 and 1/16 inch I allowed for the titles column on the left side.  I may go with that and either expand the titles column width or just leave the width as is and let it wrap.  We're only talking a handful of instructions here - the usual Basic ones, plus the oddball variations in the sub-languages (AMAL, Interface & Menu).  So taking an extra line when it wraps isn't going to add much to the overall document length.  (Or maybe just "Flow"?    ).

"Flow" looks good 

[MadAngus]

Flow sounds good to me, it's pretty much clear in it's meaning, certainly better than "structure".

[Lonewolf10]

All the commands, tables, examples, etc, are now in the database including the missing ones.  Without doing a trawl through the machine code in the AMOS executables and libraries , I'm pretty sure I've got them all.  But may do that trawl anyway to make sure.  Saving it up until I need a break from the manual editing!   

No need to. That is exactly why I created the AMOS Extension Examiner, which has been available on Aminet since 18th March 2011:

http://aminet.net/dev/amos/ADBs_Ext_Examiner.lha


If there are extensions it doesn't work with then let me know and I'll try to fix it. I tested it with all the ones I have (60ish) with no problems. It doesn't do AMOS executables though, only the extension (.lib) files found in the APSystem and AMOS_System drawers.


Thumbs up a cool project


Regards,
Lonewolf10

[bruceuncle]

Been away for a while, hadn't even logged in   A bit of tracking down legacy docs and code for a client occupied my time for a while.  And the far, far more important task of replacing my dinosaur mobile with a smartphone.

No need to. That is exactly why I created the AMOS Extension Examiner, which has been available on Aminet since 18th March 2011:

Thanks for that Lonewolf10 - I'll give it a go next week.  The ones I'm specifically after are any that may be undocumented in the AMOS Pro 'core' executables.  That's how I tracked down the 'missing' stuff in the Interface sub-language - never could resist a bit of disassembly and 'pattern matching' on 68000 executables.  Only to find they were already mentioned in the original help files, just missing from the original manual.  Oh well, it was fun anyway. 

Still plod, plod plod as I wade through all this stuff.  I'm not going to count them one-by-one (there's a few non-instruction 'comments' in the 'raw' help file content) but I'm up to around 850 instructions in the language.  (That's total, not where I'm up to, I hasten to add.)  And that's not counting the 97 editor commands as they haven't yet been incorporated as formal 'references'.  (My own term for what anyone else on the planet would probably call an Index entry - one per AMOS Pro Basic instruction.)  So it looks like AMOS Pro Basic has around 950 instructions in it's core dialect. 

I also found some time to do the final 'refactor' on the database-to-RFT writer and do a major rationalisation of the database structure.  Now that I'm happy with the resuts (and MadAngus seems pleased with the content and format styles) it made sense to get it all properly normalised, etc. 

As I plough through this, I'm beginning to dread the pagination effort at the end.  That has to be done by hand after importing the RTF into Word.  Looks like I'm up for around 1,000 or so pages to be done!  Wish me luck.  But it will be a while yet before I get to that stage...

Also found the time to catch the first 'flu of the season (autumn on this side of the planet) so I'll end this update before any of you guys get infected 

[MadAngus]

@Lonewolf10, bruceuncle

Thanks for the notes and progress updates folks.

Here's my little progress report:
The Typesetting/Styles consolidation is as complete as I'm going to get it for now.
Easy AMOS Manual (Rev 1) is done except the index.
Volume 2 (Rev 1) of the AMOS Club Newsletters are nearing completion.
AMOS Pro User Guide (Rev 1) custom styles are defined and the document is about 40% complete.
jAMOS Manual has been started in earnest but I will not be releasing any wip versions for a while.
My little Amos Manuals Project Typesetting Guide has the skeleton written, just need to add the meat.

I'm working on the Index concordance file at the moment, the XML schema design (XSD) is done and now I'm working on the translation code to extract XML instances data and produce a linked index automatically.
I'll release this when it's done for anybody who might have a use for it.

I want to get a few other OpenOffice tools written as well, then I'll do a bulk release of documents etc after I've tied everything together. I'm putting a lot off hours into this now (20-40 hrs/wk) so it should be a only matter of weeks (not months) until a release.

I want to get Phase 1 complete in a final push and single release, for that reason the dates in the schedule have been removed.

[bruceuncle]

Yep, definitely moved into the once-a-month update realms.

Nothing earth-shaking to report this month.  A client keeps doling out 'work' work for me to do, so time has been a little limited lately.  So it's still plod, plod, plod 

I did re-visit the flow control structures section as a break from purely-AMOS instructions.  Originally, this section followed the same format as the rest of the reference - documenting keywords.  This results from the source of the material being the Help Files, where keyword look-ups are the intent.  For the flow control structures, this made for a very repetetive section (If being documented separately from Then, Else If and End If for example).  I've revised it into two sections, one to group the keywords as flow control structures and one as purely a keyword reference.  Looks and reads a lot better and saves a lot of space as the keywords section mostly just refers back to the structures section.  Haven't come across the need for this elsewhere yet as, although there is repetition in some areas, it's nowhere near as messy as the original flow control section was.  And I can happily live with that.

Also revised the way multiple syntax formats for an instruction are handled.  These are now numbered and grouped by syntax variation.  So instead of grouping all variations under each heading, it looks like this example:

Statement	Read Text$
Description	Statement that displays some text from either a file, or a memory bank using an attractive, on-screen text reader.  It has two formats:
1:Syntax	Read Text$ Filename$
1:Parameters	Filename$ is the full path for the file to be displayed.
2:Syntax	Read Text$ Title$,StartAddress,Length
2:Parameters	Title$ is diplayed as the screen title.
	StartAddress is the memory address of the first line of your text.
	Length the length of the text in characters.
Remarks	First format loads a file into memory, and displays it on the screen in ASCII format, using Filename$ for the title.
	Second format displays a memory block on screen in ASCII format, using Title$ for the title.
	You can move through the displayed text using scroll bars, the arrow icons or via the following key combinations:
	Key Press                                       Effect
	[Up Arrow]/[Down Arrow]                Move up/down by one line
	[Shift]+[Up Arrow]/[Down Arrow]    Scroll up/down by one page
	[Ctrl]+[Up Arrow]/[Down Arrow]      Jump directly to top/bottom of text
	[Esc] or [Return]                             Exit
Example	Read Text$ Fsel$("**")
See Program	AMOSPro_Examples:Examples/H-8/Help_82.AMOS :  Read Text$

This involves a fair bit of revision over stuff already done.  But I think the results are a lot easier to use.

That's all for now.  Next report end of June.  I'll try and get the revised Interface quick ref (same as the existing one, just bringing the styles in-line with the manual) and a new AMAL quick ref out by then (a pleasant break from the main slog) but it will depend on how much time I get.   

[MadAngus]

I like what you've done, it does read a lot easier. With the various options in one place under one heading it has the added advantage that a reader will immediately be aware of all the options, rather than missing them if they were in under other headings.

Myself, I am currently working at an absolute snails pace as I am in the process of moving house and clearing out all my other projects, so I can concentrate on technical writing and related projects.

This means that I am no where ready to release anything not even wip docs until I get things sorted.

[bruceuncle]

AMOS Professional 2.0
I'm testing out the documentation against reality for the AMAL language subset.  And I've come across an anomaly with the AMAL "mouseKey 1" and "mouseKey 2" functions:

"mouseKey 1" returns -1 (True) when the left mouse button is pressed and 0 (False) if not - exactly what the manual and help files indicate should happen.
"mouseKey 2" however, returns 0 (False) when the left mouse button is pressed and -1 (True) if not - the complete opposite behaviour and contradicts the manual and help files.

I can document this behaviour 'as is' for the reference manual and quick ref guide.  But need some confirmation that this is 'normal':

• Is this what everyone else gets?
• Was there any later 'fix' published?

My setup is AMOS Pro 2.0 ('straight out of the box' with no patches applied) running in WINUAE.
AMOSPro.lib shows up as Version 2.00 and is 98,184 bytes long (just in case my copy differs from everyone else).  Or is AMAL functionality in any other library?

A simple testbed program:

Load "AMOSPro_Tutorial:Objects/Amal_bobs.abk"
Screen Open 0,320,200,8,Lowres
Curs Off : Flash Off : Cls 0 : Get Sprite Palette : Hide
A$="AUtotest(Let RB=K2;If K1 Direct Quit else eXit) "
A$=A$+"Let X=XH(0,0); Let Y=YH(0,100); Let A=5;"
A$=A$+"Let R1=XH(0,320); Let R2=XH(0,0);"
A$=A$+"Let RA=0;"
A$=A$+"Forward: Let R0=-1; Anim 0,(5,4)(6,4)(7,4)(8,4); Move 320,0,160;"
A$=A$+"Backward: Let R0=1; Anim 0,(1,4)(2,4)(3,4)(4,4); Move -320,0,160;"
A$=A$+"Jump Forward;"
A$=A$+"Quit: Let RA=-1; End;"
Wait Vbl
XX=X Hard(0,0)
YY=Y Hard(0,100)
Sprite 2,XX,YY,5
Amal 2,A$
Amal On
Repeat
   Wait Vbl
   Locate 0,15 : Print Amreg(1);
   Locate 0,17 : Print Amreg(0);
Until(Amreg(0)<0)
Amal Off
Show
Direct

The above code is testing out a few other functions at the same time and is obviously 'overblown'.  But that's the whole point of testing this stuff against the docs  .

Any and all comments welcome.

[MadAngus]

Just a note, I'm moving house tomorrow.

All my computery stuff is packed away except my internet PC. As well as the unpacking, I've still got the kitchen to do (got to re-plaster all the walls), and only the heavens know when the broadband is going to be reconnected in the new house.

When all that's done I've still got to eBay and AmiBay all the stuff I want rid off and there also uploading Lonewolf's extentions here (I haven't forgotten ). So basically I'm still in hiatus for a while as far as manuals are concerned.


The other half is currently brandishing a frying pan demanding I get off this computer and finish packing.

See you soon - Ducks frying pan and logs off.