Request : User doc

Can I make a request for either the official or community IDE (or for Quark)?
Can the documentation (docmods?) be made to create the official doc but then also look into /commands/userdoc (or wherever) and append the user data.
That way we can write, and share, our own doc improvements.

tonyg,
Would the system I've created here http://www.blitzmax.com/Community/posts.php?topic=70704 be an alternative?
The user created examples can have links to tutorials (see function CreateWindow as an example), forum links (see incbin) and even wikipedia (see atan2)

An official solution, would of course, be better

Yep, that would certainly help.
However, as you mention, an official answer would be great. Not only would I be able to append user created examples BUT I'd like to enter my own notes, links to examples on my machine and examples written specifically for me to understand.

Sounds very useful, actually.
But it would need to be easy to use/manage.
Lots of individual files ? One per module, split into sections? One per item?
Perhaps some way to describe a certain item...
commands/userdoc/brl/pixmap/loadpixmap.bbdoc
commands/userdoc/brl/pixmap/tpixmap.window.bbdoc

some kind of integration with the IDE would be nice too...

Personally, I would like Bmax documentation to have a link to a User_<command>.bmx file (e.g. user_loadpixmap.bmx) where I can add an example (or more) and any comments.
I must admit I haven't thought the solution through as much as the need.

If anyone has any more ideas... I could have a look at implementing something.

Would you expect user documentation to work for third party modules as well? One issue here is that some authors tend to code OO rather than procedurally, so you'd need the ability to specify type.method/function too, I suppose.

Unless you are after a very basic system, of course...

I only envisaged BRL modules as 3rd Party code tends to document in 101 different ways anyway.
Without HotDocs or trawling through the source users wouldn't notice type methods and functions the way BRL code OO.
Just the standard commands (e.g. those listed in the Index) would be required.
The obvious requirement would be to ensure the data is kept between installs/build/docmods (whatever).
What would be VERY good is to be able to download a community package and add the data
e.g. user_<command>.bmx
community_<command>.bmx

So you envisage these files as actual runnable code examples ?

Not necessarily although that would be handy.
Before I realised all my additions would be lost I began to add different examples in the same .bmx with
rem/end rem statements around each example.
Any specific notes I was adding to the normal documentation but adding them as comments in a .bmx file could be OK... I think.
<edit>
Ideal would be for each command help page to show :
1) BRL doc/example
2) User doc/example
and/or
3) Community doc/example.

How about two files... one for notes, one for example?

doc/user/loadpixmap.bmx
doc/user/loadpixmap.bbdoc (or txt) - or not if you don't want it.

otherwise it possibly complicates the need to make sure the code is commented properly...

Checkout my implementation of this idea.
Download the compiled chm file http://www.2dgamecreators.com/files/BlitzMaxHelp.chm then as an example, look a the CollideImage function where there is a BRL example, a user example plus a link to a tutorial.

What I do is read the official docs folder then whilst parsing these check to see whether a user example exist for a particular function then combine them into a new html file in a folder structure which mirrors the official doc folders.

The problem with a chm is its lack of integration with the default IDE. It's a great document, but I prefer help to be available in the same app.

Anyhoo... how's about this :



..showing loadpixmap with user/community docs and examples, using the folder structure mention in my previous post. (I included CreateStaticPixmap function in the screenshot to show the difference between the two..)

Brucey,
Thats good. I can zip up the examples that I have (almost 300 of them in html format) which you can then incorporate into this structure as community examples.

Sure... mail it to me if you like (see profile), and I guess I can "un" html them and turn them into proper examples.

The split between doc and example should make it easier to provide some good descriptions with links and such.

Brucey, Check your email

Thanks assari :-)

Currently the revised docmods supports as follows :

* docs in these folders ...

*** BlitzMax/doc/user
*** BlitzMax/doc/user/<namespace>/<module>

*** BlitzMax/doc/community
*** BlitzMax/doc/community/<namespace>/<module>

where, <namespace> would be something like brl and <module> could be timer, both lower case.

Extra notes take the form of <identifier>.bbdoc
Examples take the form of <identifier>[1..].bmx

where, <identifier> would be something like CreateTimer, and examples having an optional index if there are more than one.

A full example :

BlitzMax/doc/community/brl/timer/CreateTimer.bbdoc
BlitzMax/doc/community/brl/timer/CreateTimer.bmx
BlitzMax/doc/community/brl/timer/CreateTimer1.bmx

If you don't want to go to the hassle of the folder structure, doing the following is also allowed :

BlitzMax/doc/community/CreateTimer.bbdoc
BlitzMax/doc/community/CreateTimer.bmx

(but obviously, if something were to use the same name in different modules, you might get things appearing in unexpected places)

..and the same format applies to the user area.

The .bbdoc files are formatted before integrating into the documentation, which means you don't have to use too much HTML to make it look ok. (like for paragraphs, tables etc)

Currently doing some testing and conversion of assari's docs to fit into the structure.

Any comments/suggestions?

:o)

A simple formatting suggestion - would be nice to make the community / user docs visibly different from the official docs, e.g. different pastel colour for the background. I guess that would require an amended the css though...

Happy to plug any simple changes to support this into the CE IDE. Although I've decided to hold off making substantial changes to the CE IDE, I'm still up for minor tweaks. The most obvious thing that would be needed is a "synccommunitydocs" function, but the community docs would need hosting somewhere...

Also, if you're thinking about the docs, I've always thought the biggest improvement would be a simple search facility. Never quite found time / fancied writing one, but knowing you, thought I'd just mention it, see if it caught your eye... ;-)

Nothing required here since the code lies in docmods which build everything into the standard docs.
Unless, as you mention, some ability to sync the community docs is required.

I've pondered the search thing in the past. I had considered perhaps an SQLite-based jobbie, but I guess that's over-kill for something like that. Docmods needs to create a nice set of data that is quick to process. Then all we'd need is another option in the IDE to search and display.
What do we make searchable? Just the keywords, or everything... docs and source?

My thinking was always that once you go to the bother writing a search function, it might as well do full text searching. But then, I've never written a search program / algorithm in my life, so not sure I'm necessarily right!

Keywords would probably be sufficient (and might allow for neat (but potentially a bit random) see-also linkage off each keyword), although often the problem is "I need to do 'blah', but can't find / didn't know the command".

A revised docmods : Download Source (30k)

Assari's chm examples (brl.mod) in a docmods compatible format : Download (189k)

Docmods should be compiled in Release mode and non-GUI. (although for testing, it will run from the IDE in debug mode). Handy if you want to see how it looks, but without installing it in BlitzMax/bin.

The examples/notes "community" folder should be dropped into the BlitzMax/doc folder. Also included is an updated bmxstyle.css which should also go into the BlitzMax/doc folder - adds enhanced colours for user/community notes and examples. (Note : the MaxGUI examples still need to be finished... but the rest is done)

Brucey, I have just got around to trying this out and it is absolutely superb.