Ultimate Amiga

Please login or register.

Login with username, password and session length
Advanced search  
Pages: 1 2 3 [4] 5 6 ... 9   Go Down

Author Topic: AMOS Manuals / AMOS Pro Resource Kit Project  (Read 49600 times)

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #45 on: February 23, 2012, 11:00:17 PM »

Quote
Did you really mean A4 Landscape for the 'cards'?

Landscape is only a preference.

What ever works best for the layout, some of the content will probably not work in landscape, no point banging your head against a wall trying to fit it in, I'm also easy either way. ;)
Logged
My shadow says otherwise.

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #46 on: February 29, 2012, 05:23:38 AM »

Another Idea for the resource kit I am adding here for reference purposes.

AMOS Magazine article collection.

Collate all AMOS magazine articles ever published in commercial magazines.
Gain permission to re-publish from the copyright holders
Produce a super AMOS mag containing all articles.

Also added some edits to the Resource Kit Project Breakdown -> Here
« Last Edit: February 29, 2012, 07:37:01 AM by MadAngus »
Logged
My shadow says otherwise.

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #47 on: March 01, 2012, 11:02:25 PM »

Thanks MadAngus, I've read all those changes and like the way the project is developing.   8)

I'm in the tedious and very time consuming stage of ploughing through the database editing stuff, matching examples, testing examples and testing 'limits'.  The 'limits' are something missing in some of the original docs.  For example, Print Mid$("abcd",0,97) will not give an error, but just what is the result?  Many of the Basic statements and functions familiar to programmers in other dialects do not behave quite as expected.  In one respect this is useful as it cuts down on error and bounds checking, etc. which, in turn,  cuts down code size for those still working in limited memory.  I've included these unexpected limits and behaviour for familiar commands in the reference manual.  Which makes some entries not quite as terse as desired.  However, it's useful I think.

Note that I keep banging on about 'the database'.  All revision is being done in the database not in a final document.  Reason being that it's then a doddle to export whatever sections or level of detail may be required in other projects.  For example, if you just want the Syntax, Parameters and Return Value sections for AMAL statements and functions, it's easy to query and export it - ready formatted in RTF if required.  I can see it saving a lot of time down the track both for myself and anyone who needs organised doc text.

It also follows one of the basic tenets of data storage - "Store each piece of information in one, and only one, place."  I realise this probably makes little sense unless the database is available to everyone!  However, I'm trying to look to the future where it could maybe drive a Wiki?  As Lego says "Limited only by your imagination".

Progress Report

Well some of that's in the waffle above.  Editing and tidying up over 700 commands is taking some time.  I'll just give a weekly progress report so's you don't think I've expired or overdosed on pizza or caught amnesia or have to work on a contract or something.

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!   ::)

The early sections of the manual are just about complete - the meat's there, I'm only re-checking that everything's as I want it.  So, using the section headings in AMOS Help, that's:
  • Using Help
  • Editor
  • Direct Mode
  • Syntax Conventions
  • Basics of AMOS
The to-do list is:
  • Screen Control
  • Object Control
  • Audio
  • AMOS Interface
  • Input/Output
  • AmigaDos
  • Debugging
  • Machine Code
  • Tables
  • Appendices

The Appendices is where I'm stuffing anything pulled in from other sources.  So far, this includes (and not in any particular order yet):
  • The example programs listings in full
  • Ask Editor and Call Editor commands
  • AMOS Equates stuff
  • The 'Latest News' bits and pieces

Some of these will migrate into the main manual (Editor commands being obvious) and some chunks of example programs are already being used.  I'll decide what to do with the rest later.  I want to concentrate on the existing 'meat' for now.

Any ideas, inclusions or suggestions welcome.  Just bear in mind that this is a reference work for just the AMOS Basic core language, not for any tools (Compiler, Object Editor, et al) nor for any Extensions (3D, AMCAF, et al).

So, long a way to go yet, but I'll keep posting these weekly updates. :)
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #48 on: March 02, 2012, 08:03:55 AM »

Thanks, for the update. :)

Quote
I can see it saving a lot of time down the track both for myself and anyone who needs organised doc text.

It will, as at the moment I am primarily concerned with the outlining/structure of the documents. This way your data can be dropped straight into the relevant section.
Logged
My shadow says otherwise.

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #49 on: March 02, 2012, 11:27:52 AM »

Quote
The Appendices is where I'm stuffing anything pulled in from other sources.  So far, this includes (and not in any particular order yet):
  • The example programs listings in full
  • The 'Latest News' bits and pieces

Could you elaborate on why you are adding these elements to the Quick Reference, as we agreed they do not belong in this reference. ???

[Edit] On a further note I am half way through structuring the Easy AMOS Manual. I am also in the process of delving into the Open Document Format specification for designing the SQL/PHP online manuals database.

I have also moved the "Resource Kit Project Breakdown/Plan" post to a separate (locked) topic to ease the management of the breakdown/plan. Any comments should still be posted here.
« Last Edit: March 02, 2012, 06:10:36 PM by MadAngus »
Logged
My shadow says otherwise.

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #50 on: March 04, 2012, 05:31:31 AM »

Thanks for the feedback Mad Angus.  I didn't put it too well in that last post , so I can understand your alarm!  ;D

Quote
Could you elaborate on why you are adding these elements to the Quick Reference, as we agreed they do not belong in this reference.

My bad terminology!  They're only in the database, not the manual.  It's just a lot easier for me to reference them and pull appropriate text out if they're all in the same structure rather than have them in separate documents.  And the Appendices are just a good storage area for the time being.  As I put it:

Quote
The Appendices is where I'm stuffing anything pulled in from other sources.  So far, this includes (and not in any particular order yet):
...
Some of these will migrate into the main manual
...
I'll decide what to do with the rest later.

My latest thinking is:

 :'( excluded - The example programs listings in full - thanks for the reminder.  I'd already ruled them out anyway as there's over 19,000 lines!  They're there at present to pull a few example lines from.  Which has proved to be more fruitless than I anticipated as there are some holes and they haven't kept up to date with AMOS Pro 2.0.  And to check the integrity of the "See Example: xxxxx.AMOS" references from the manual.  Which, the way they're going so far, may end up instead as "See Example: xxxxx.AMOS, which won't work but may give you a vague idea;D .
 
 :) included - Ask Editor and Call Editor commands - these will go into the manual as sub-topics for the Ask Editor and Call Editor topics.  They're analogous to the Interface, AMAL and Menu sub-languages.

 :-\  dunno - AMOS Equates stuff - may not be appropriate for the manual.  May be suitable for an appendix or a separate guide.  Need to know more before making any decision.

 :'( excluded - The "Latest News" bits and pieces - these are just there for my own info as they contain bits and pieces about corrections, new stuff and so on.

And don't worry about the origin of sources for example code in the stuff I'm doing.  It all comes from either the original AMOS Pro Disks or the original AMOS Pro Manual or me.  As mentioned above, some of the examples on the disks aren't as useful as I'd hoped.  Where there's nothing suitable in an example program nor in the manual, I've made up new ones following the same style as the existing ones.
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #51 on: March 04, 2012, 08:42:55 AM »

Quote
excluded - The example programs listings in full
included - Ask Editor and Call Editor commands
dunno- AMOS Equates stuff
excluded- The 'Latest News' bits and pieces
Agreed, makes sense.

All the stuff not going into the quick reference(s) and reference cards can go in a temporary extras section for online access. The UltimateAmga's database uses MySQL so you might want to consider porting your extras to MySQL tables when your ready. Also consider the structure of the database (extras content) and how that would relate to an online front end (categories). In the first instance We'll use your table structure for the extras section(s). We can discuss the details further down the line.

Thanks and keep up the good work. :)
Logged
My shadow says otherwise.

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #52 on: March 11, 2012, 09:15:46 PM »

Nothing much to report this last week as some inconsiderate b@#!*y client called me and wanted some urgent work done.  However, that's now out of the way so I should be able to plod through some more stuff this coming week.

Slow work as I'm having to test and explore some aspects of the language as I go.  Will post again next week with, hopefully, a better rate of progress.  :)
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #53 on: March 11, 2012, 10:23:19 PM »

 :) Ah! one off those weeks.

No problem, we get things done when we can. ;)
Logged
My shadow says otherwise.

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #54 on: March 14, 2012, 04:23:13 AM »

A little bit of progress after losing a week having another battle with OpenOffice, lost 4 days work, bad OOo, and 3 days trying to get OOo to do what I want i.e. turn OOo into a pseudo-DTP application.

The outcome of that battle, as well as turning OOo into a pseudo-DTP application, was progress on the style consolidation, which has turned into Object Orientated Typesetting. So I've got a good number of styles defined.

Defining the styles has allowed me to visualize the code behind the dialog, and in turn write some test parsing code to rip out the ODF styles and convert them into CSS groupings. This code will eventually find it's way into dbODF.

Nothing spectacular, I'm just in a really good mood after the current OOo battle, so I thought I'd share the joy. ;D

Now all I need to do is get psyched up for the FreeBSD scripting dance to replace my windows desktop webserver. I'm hoping eventually to be able to use my MS-Windows CD's as Frisbee's. ;)

[Edit 15/03/12] 133 styles defined at last count. All told I reckon there will be about 200-250 custom styles.
« Last Edit: March 15, 2012, 03:04:50 AM by MadAngus »
Logged
My shadow says otherwise.

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #55 on: March 20, 2012, 09:38:40 PM »

The not-quite-weekly update.

While MadAngus has been struggling with his can of worms, I've been absorbing the full lexicon of RTF markups.  Buried deep in the five-and-a-half-thousand pages was the stuff I needed ::)...  Have a look at http://www.ecma-international.org/publications/standards/Ecma-376.htm and download "ECMA-376, Third Edition, Part 1.zip" if anyone's interested  :'(.

Anyway, I'd taken some time off the acutal re-writing-of-the-reference-manual-from-the-help-files task and concentrated on completing the database software to output the finished document.  I rejected Word 2010 and its VBA to do the dirty work for me as the b@!%#!! thing crashes every time I put a watch on one of its objects to see what its doing.  RTF is a much better alernative as, besides being portable, I now understand it :)!

The process now is to output the document direct from the database with contents and indexes already in place, with fully resolved bookmark hyperlinks but dummy field results for page numbers.  Then paginate the document in Word 2010 (no way am I going to attempt that in RTF as measuring the text is a whole different ball game) and finally tell it to refresh the fields.  Works a treat in the trials I've done 8).  I do format some of the obvious pagination in RTF - after title page, after contents pages, for major heading changes and for index start/finish pages.

The only downside to this method is that Word will no longer understand contents and indexes as fields that it can update.  I did try forcing page number hyperlink references into the indexes, but Word deftly removes  them when it refreshes the indexes.  This is because an index is just one big field as far as Word's concerned, so it rewrites the lot each time it's refreshed ::).  I don't regard this as a problem as I edit all content in the database, not in Word.  Word is now only used to manually paginate, refresh fields and output as PDF.

The hyperlinks from the indexes work fine using this method as each topic is bookmarked.  The only hassle is deriving unique bookmarks - and one reason I stopped work on the meat of the document until I sorted how they were going to be used.  A fair number of AMOS Basic instructions (the topics) are duplicates on name alone but unique in their own context.  For example, "As" appears in "Reserve Bank As xxx" four times and "Mid$" appears as both a statement and a function.  So these have to be qualified before they can be used as a topic heading and bookmark.  For example "Mid$ (Statement)" and "Mid$ (Function)" to give unique names.

Cross-referencing for the "See Also" entries uses the same bookmarking/hyperlink process and works perfectly too.

Completely off-topic - we had a foot (30cm) of rain just over a week ago, so I've also had to machete the jungle - some weeds were taller than me when the rain stopped!

Should be back to the grindstone of the meat of the document "real soon now".

MadAngus: I will mail you that sample I promised a couple of weeks back.  Some time this week.  Just a section out of the parts I regard as just-about-finished so's you can approve/disapprove the content and format, etc.  Good luck with your bits and pieces. 
Quote
133 styles defined at last count. All told I reckon there will be about 200-250 custom styles.
That sounds like a mega number of styles you're playing with there!  I'm only using couple of dozen...  But then, my techo reference is a pretty boring document in some ways ;).
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #56 on: March 21, 2012, 01:29:47 AM »

Quote
While MadAngus has been struggling with his can of worms, I've been absorbing the full lexicon of RTF markups.  Buried deep in the five-and-a-half-thousand pages was the stuff I needed ::)...
lol, no small amount of reading then, must be paddling the same boat as I am (except I haven't got a paddle). ;D

And then there's the HTML version and that's another can of worms.
Worms for breakfast, Worms for lunch, Worms for dinner, and there's even a game of Worms. *sigh* bet there's a movie too. ::)

Quote
The only downside to this method is that Word will no longer understand contents and indexes as fields that it can update...
What is it with OpenOffice Writer and Microsoft Word Developers, it seems like the importance of outlining and indexing has taken a permanent backseat, 10+ years and little progress in these areas. :(

Quote
The only hassle is deriving unique bookmarks...
I'm facing a similar problem with the auto-index code, some of the index entries text do not correspond to a matching word on a page. In these cases it is more a reference to a paragraph and it's not always clear which paragraph is being referenced. Have a solution at hand, so not a problem I need to worry about.

Quote
Completely off-topic - we had a foot (30cm) of rain just over a week ago, so I've also had to machete the jungle - some weeds were taller than me when the rain stopped!
Will we just call you Indie then, Indiana 'bruceuncle' Jones and the 30 foot weeds. ;D

Be careful there could be Triffids in them there weeds.
Triffids - Wikipedia

Quote
That sounds like a mega number of styles you're playing with there!...
ODF styling is similar to CSS, even the smallest change in formatting results in an style being auto-created by OOo. By having a predefined set of styles to work from I am not generating a host of additionally auto-created styles, and in turn reducing the overall number created.

e.g. There are nearly two hundred quotations in the Easy AMOS manual and I am using frames to hold them. If each frame was positioned slightly different and/or sized to fit each quotation. OOo would create a style for each frame, 200-ish frame styles :o, I think not. By creating one quotation frame style with generic settings that can hold any quotation I actually reduce the number of styles, in this case too one.

Also, predefined styles allows the identification of styles that can be consolidated to further reduce the number.

I should mention not all the styles are used in each document, in a sense these styles sets are similar to the printing dies sets that typesetters used in the early days of printing. Pick and click, speeds up typesetting. ;)
Logged
My shadow says otherwise.

MadAngus

  • There is no spoon.
  • Site Admin
  • A500
  • ****
  • Karma: 5
  • Offline Offline
  • Posts: 497
  • AMOS Docs / AIAB Dev
    • AIAB (Amiga In A Box)
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #57 on: March 21, 2012, 03:52:24 AM »

Right, the current quarterly scheduling system is a complete disaster which I do not work well under. I'm going back to the tight deadlines I used previously. Even with delay's I got a lot more work done than I'm getting done now.

I'll be updating the scheduled release dates so keep you eye's on them for changes.
Logged
My shadow says otherwise.

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #58 on: March 21, 2012, 08:05:07 AM »

Quote
Quote
The only hassle is deriving unique bookmarks...

I'm facing a similar problem with the auto-index code, some of the index entries text do not correspond to a matching word on a page. In these cases it is more a reference to a paragraph and it's not always clear which paragraph is being referenced. Have a solution at hand, so not a problem I need to worry about.

One solution I originally looked at was to:
  • Bung all the stuff I wanted to use as bookmarks into a table, linked to the stuff each was referencing
  • Generate bookmarks from <each topic name> + <a sequential number>
  • Use that table to look up each bookmark as I need it
Downside is that the user then gets something like "Mid$_1234" as the bookmark name displayed as they hover the mouse over a hyperlink.  However, a bit more digging in the RTF bible uncovered an option to specify the "tool tip" text for a hyperlink, which I assume is what it would display instead.  Only just stumbled across this one, so I'll try it out after supper and let you know if it works as expected.  Would save a lot of heartache in thinking up unique bookmarks and detecting duplicates...

Quote
Quote
Completely off-topic - we had a foot (30cm) of rain just over a week ago, so I've also had to machete the jungle - some weeds were taller than me when the rain stopped!

Will we just call you Indie then, Indiana 'bruceuncle' Jones and the 30 foot weeds.

Be careful there could be Triffids in them there weeds.
Triffids - Wikipedia
Have you ever seen the seriously baaad 'B' grade movie?  So baaad it isn't even funny.
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."

bruceuncle

  • AMOS Dev
  • A500
  • *****
  • Karma: 6
  • Offline Offline
  • Posts: 425
  • WINUAE Amiga User
Re: AMOS Manuals / AMOS Pro Resource Kit Project
« Reply #59 on: March 21, 2012, 09:39:27 AM »

Quote
an option to specify the "tool tip" text for a hyperlink
Yeah, that works ok.  I would assume that most markup languages would support this sort of option for a hyperlink (same as HTML does)?
Logged
Repeat after me ...  "The AMOS Pro architecture is complex but it is not complicated."
Pages: 1 2 3 [4] 5 6 ... 9   Go Up
 

TinyPortal 1.6.4 © 2005-2019