Clearly, it is important to ensure that changes made to Yabasic are reflected accurately in the language's documentation. With Yabasic 3 introducing several major new features and many alterations on a more minor scale, it seems logical to write a completely new manual. Elmar Vogt has volunteered to take on this daunting task, and plans to start working on the manual this spring (read "autumn" if you live in the Southern Hemisphere).
Elmar intends to use LaTeX for document formatting, and, as a result, Yabasic's manual will be distributed in at least two widely-accepted formats: as a nicely-laid-out PDF document, and as an XHTML document for easy browsing and searching.
Hi all,
ReplyDeleteAs the official "Documentation Manager" (Ha!) for Yabasic, perhaps it's time I introduced myself.
On the basicprogramming board and some other places on the planet I go by the nick of "syzygy". I am a physicist, software developer and tech writer, and lately I thought I ought to get more involved with the open source scene again. And since I very much liked the concept behind Yabasic (but never really got to do a whole lot with it), I approached Thomas that perhaps I could write up some documentation about the new V3... and thusly was promoted to "Head of all things written". Well.
I hope to be going full steam with the Yabasic documentation in February or March at the latest. I'll use LaTeX simply because it's the text setting system I'm most familiar and comfortable with. Primary output will be PDF, but since several people have asked for a HTML version, I will try my hands on that one as well.
To convince you that I haven't been completely idle, here's a preliminary project plan/table of contents for the Yabasic Vademecum I'm planning to write: (Of course, the blog engine will ruin whatever formatting there ever was...)
[0%] Overview
[0%] History
[0%] License
[0%] This is not a BASIC primer
[0%] People, web addresses, resources
[0%] Installation and use
[0%] Installation
[0%] Unix
[0%] Windows
[0%] Command line options
[0%] Calling with no parameters
[0%] Binding
[0%] Code from the command line
[0%] All options
[0%] Features and concepts
[0%] Binding
[0%] Binding from runtime
[0%] Binding from the interpreter
[0%] Syntax
[0%] Character sets, "identifiers"
[0%] Commands, Whitespace, Lines
[0%] Modules and Libraries
[0%] Libraries
[0%] Creating
[0%] Using
[0%] Modules
[0%] Creating
[0%] Using
[0%] Variables
[0%] Types
[0%] Float
[0%] Strings
[0%] Arrays
[0%] Structures
[0%] User-defined types
[0%] Pointers
[0%] (11.1.10) Variable scope: local and static
[0%] Control flow
[0%] If else / On / Switch case
[0%] For / Next
[0%] Do loop / Repeat / While
[0%] Break / Cont
[0%] Procedures and functions
[0%] Passing parameters
[0%] I/O: Use of terminals and windows
[0%] Coordinate systems
[0%] Compile and Execute
[0%] Reference
[0%] Alphabetical
[0%] ... by topic
[0%] Keywords
[0%] Functions
[0%] Math
[0%] I/O
[0%] String
[0%] Graphics/Sound
[0%] ... by module
[0%] Sample applications
[0%] LaTeX: Benötigte Formatvorlagen
[ ] Yabasic-Schriftzug
[ ] Befehle
[ ] Code/Beispiele
[ ] Specifications (Boundaries...)
[ ] New to V3
[ ] Changed V2.763 -> V3
I'll keep you updated as to the development of the whole thing.
Also, please be aware that EK Virtanen and others are currently also working on Yabasic documentation, though in the shape of a blog. (It is my conviction that documentation is like money: There can be too little and too much, but never enough of it. ;-)
Cheers,
syzygy
I have to admit that I am very impressed by the preliminary table of contents...
ReplyDeleteThomas.
By the way--don't worry about writing a separate manual in HTML! We'll work out a way of converting LaTeX to HTMl, even if it involves writing a small Yabasic script. :-)
ReplyDeleteThomas.
Well, Thomas, this is what I do for a living... so I'd better be good and a little ambitious about it. ;-)
ReplyDeleteBesides, every now and then I find a cool bit of software out there which looks really nifty, but I can't seem to get a grip on it, so I abandon it again. This should not happen to Yabasic 3...
As for the HTML version, I know there are LaTeX-to-HTML filters out there, so they'll produce *some* result. I just have no idea how good or bad this will look. We'll see.
What I wanted to say with "This should not happen to Yabasic 3" is that I gave up on those pieces of software because they weren't well documented.
ReplyDeleteFirst you think, then you hit "post".