IntelliSense for commodore libraries

mithrendal commented 5 years ago

Hi prb28,

I can't really express in words how great this visual studio code extension already is. I really want to express my heartful thanks and admiration for your work.

Now I will come to the thing which might be a cool enhancement. I have a .i file with all the offsets


* Important Exec Library Offsets
AbortIO            equ -480
AddHead            equ -240
AddIntServer       equ -168
AddTail            equ -246
Alert              equ -108
AllocMem           equ -198
...

and this file I do include in my .s files. I had to install the extension "All Autocomplete" to get the constants of the .i file recognized when I edit the .s file. This leads my to a further question:

How can I extend IntelliSense in VSCode on library calls. When the mouse is over a lets say

jsr AllocMem(a6)

I would like to see a hint like this

NAME
    AllocMem -- allocate memory given certain requirements

SYNOPSIS
    memoryBlock = AllocMem(byteSize, attributes)
    D0                     D0        D1
...

Is that maybe easy possible to add to Amiga-Assembly ?

with best regards

prb28 commented 5 years ago

First (and always): thanks.

This is an interesting feature. The big part of the work is to create a bunch of markdown files for each function like DFF090_DIWSTOP. For the registers, I did a little python script to transform the web pages in markdown... This needs some work to create and review, for the rest it is easy to integrate.

mithrendal commented 5 years ago

As a starting point I would suggest this source of information

Maybe I can help you out? I could use wget and transform them into .md files?

I would suggest only to use the most important libs first? Maybe exec graphics dos intuition?

prb28 commented 5 years ago

Yes, that would be great if you get the docs in .md format!

I agree with the source (I've used this when I've modified the fs-uae boot code). The base libraries you have submitted seem to be the most important (but I'm too new to that to know).

There is maybe a difficulty with the kickstart version / compatibility with the api. I don't know if the api had much refactoring from first version to the last one.

mithrendal commented 5 years ago

Parfait ! Je vais essaye ca. Mais je vais besoin de quelqe jour avec ca je crois. On le page de cette source il y a écrit "These files are made available here free of charge ". C'est pour ca je crois il n'est pas vraiment necessaire pour demander, si on est permis pour utilisier le content des cettes fichers.

Pour la question de la compatibilite. Je pas vu des autres source en ligne. Et pour ca nous avons pas du choix. Mais je personalment crois que commodore fait le nouveau version des library sans "breaking" le compatibilite avec le vieux "executeables". Pour le debut et pour la raison de compatibilite en les deux directions, je ne vais pas inclure les entrees >AmigaDOS1.3 et surtout je vais choix seulment les plus importantes entrees de AmigaDOS v1.3.

Je espere que tu peux comprend mon francaise scolaire ....

prb28 commented 5 years ago

Ton français est excellent ! Je ne ferais certainement pas mieux avec mon anglais technique.

Il n’y a pas d’urgence à faire les fichiers.

En effet, je crois que cette documentation est accessible à tous. Pour l’api si les fonctions entre les versions ne sont pas les mêmes on peut toutes les conserver, cela sert surtout d’aide mémoire.

I can still write in English, even if it’s like a alien ;-)

mithrendal commented 5 years ago

Yes lets mix languages. In the end I think francaise is more elegant. But english is still more easy for me. Deutsch ist noch einfacher. C’est ma langue maternell.

wget was not so good, parce que seulment telecharger les fichiers, n'est pas suffit. Il faut les transformer un peux. I ended up with a mini python program. J'ai tous les fichiers de exec. Looks pretty promising. Now I have still to translate the links in the “see also:” section into the md markup style... Je vais continuer demains. When I am done I can use the python script for the rest of the libraries...

prb28 commented 5 years ago

ich habe deutsch gelernt, aber ich bin very bad at it. J’ai fini avec 0,2/20 de moyenne...

Yep python is the way... (there is perl too :-))))

mithrendal commented 5 years ago

das macht nichts !! Ma resultats de francaise aussi n'est pas bonne. Mais regarde, ... on peut communiquer! Vive l'amitie franco allemande. Haha! 😃

Schau mal hier. I have got the complete exec libarie ready. Can you use it ? exec.zip

If Amiga-Assembly is happy with it I will create the other ones with the python script ... If not let me know what's missing...

prb28 commented 5 years ago

Excellent! I’ll try tomorrow evening.

endo64 commented 5 years ago

@mithrendal Unfortunately the file you've shared is not exactly formatted as a proper MD file. There are small changes need to be done one the file, see the below picture how it look previewing as MD:

We might need to write a simple converter/fixer to format correctly. For example, put one additional newline after these items:

NAME SYNOPSIS FUNCTION WARNING INPUTS RESULTS SEE ALSO

Shouldn't be difficult anyway.

mithrendal commented 5 years ago

@endo64 Great finding, thank you. Yes I see. This is easy. I will do as you suggest and change the python generator script this evening.

mithrendal commented 5 years ago

new Version with the correctings as @endo64 suggested plus I took the parentheses out of the markup link URLs. Example, before it generated [AllocMem()](/exec:AllocMem()) now in new version it generates [AllocMem()](/exec:AllocMem) or should it be [AllocMem()](/exec/AllocMem.md) ?

exec_20190425.zip

prb28 commented 5 years ago

Looks good, but I have some weird color in the hover hover I'm looking for the reason...

mithrendal commented 5 years ago

I see, it interpretes the asterix symbol of the C-style pointer as markup information. I must somehow quote the asterix I think... Could you check whether NAME, SYNOPSIS,... looks nicer if we mark it up like so **NAME**?

UPDATE: try to replace the * before OldOpenLibrary with &ast; maybe it eliminates the green color ?

prb28 commented 5 years ago

It's using the same colors as the asm source file: 'library' is a variable, A1 is a register and * is a comment. This is because the spaces before the text is interpreted as a 'code bloc', so vscode thinks it must be in asm.

mithrendal commented 5 years ago

Ah I see... and not is blue ! 🐞 strange

And the links are not rendered but outputted as plain text ... 😩

... then we must add something to the text to make it know that it is markup and not code block, est-ce que c'est correct ? 🙊

prb28 commented 5 years ago

Capture d’écran 2019-04-25 à 21 53 51

` NAME

OldOpenLibrary -- obsolete OpenLibrary

SYNOPSIS

library = OldOpenLibrary(libName)
D0                       A1

struct Library *OldOpenLibrary(APTR);

FUNCTION

The 1.0 release of the Amiga system had an incorrect version of OpenLibrary that did not check the version number during the library open. This obsolete function is provided so that object code compiled using a 1.0 system will still run.

This exactly the same as "OpenLibrary(libName,0L);"

INPUTS

libName - the name of the library to open

RESULTS

library - a library pointer for a successful open, else zero

SEE ALSO

CloseLibrary `

I'm looking how to make the links work, don't know if it is possible in vscode.

prb28 commented 5 years ago


**NAME**

OldOpenLibrary -- obsolete [OpenLibrary](/exec:OpenLibrary)

**SYNOPSIS**
\`\`\` (remove the \)
library = OldOpenLibrary(libName)
D0                       A1
struct [Library](/exec:Library) *OldOpenLibrary(APTR);
\`\`\` (remove the \)

**FUNCTION**

The 1.0 release of the Amiga system had an incorrect version of
[OpenLibrary](/exec:OpenLibrary) that did not check the version number during the
library open.  This obsolete function is provided so that object
code compiled using a 1.0 system will still run.

This exactly the same as &#034;OpenLibrary(libName,0L);&#034;

**INPUTS**

libName - the name of the library to open

**RESULTS**

library - a library pointer for a successful open, else zero

**SEE ALSO**

[CloseLibrary](/exec:CloseLibrary)

mithrendal commented 5 years ago

Looks good. So what do I have to change ?

only the **NAME** and so on ?

what is the \`` (remove the )` thing ?

mithrendal commented 5 years ago

I accidently closed it. 😎 Git hub UI should really not combine "Close and comment" in one button... Haha. Github are you hear me ?

prb28 commented 5 years ago

Yes there is:

the bold with ***
the starting spaces are removed
the special line: ``` means 'bloc of code' (instead of starting spaces) OldOpenLibrary.md.zip

mithrendal commented 5 years ago

can I put the complete synopsis into bloc of code ? That means from first character after SYNOPSIS until the beginning of FUNCTION?

prb28 commented 5 years ago

Yes, it's the only way I found to have indented text... but I can be wrong.

prb28 commented 5 years ago

oh, no the link won't be interpreted

mithrendal commented 5 years ago

execV3.zip

let it rock ! 😎

maybe the path should it be like this ? [AllocMem()](/exec/AllocMem.md)

prb28 commented 5 years ago

Better! close to the end! but the groups of 4 leading spaces must be removed and the bloc of code cannot contain a link. here is a modified file: MakeLibrary.md.zip For the links, [AllocMem()](/exec/AllocMem.md) ... I'm still searching what should be their format. I think I'll have to refactor them on the fly by adding the plugin path.

prb28 commented 5 years ago

I've pushed some modifications, so, if you want, you can try yourself. I still haven't found a good way to navigate in the documentation. doc files: https://github.com/prb28/vscode-amiga-assembly/tree/master/docs/libs/exec

mithrendal commented 5 years ago

Question: when there are more than 4 leading spaces in a line. For example there are 6,

should the python generator script remove the 4 spaces only and leave the 2 spaces in the line or should it remove all 6 leading spaces from that line ?

prb28 commented 5 years ago

If there is leading spaces it will not be considered as the same paragraph. So yes all 6 must be removed.

mithrendal commented 5 years ago

Easy. Will repair that this evening. Together with the links in the code block.

What about leading spaces inside the code block should I remove them too? In your examples you did not.

prb28 commented 5 years ago

In the code bloc the spaces look good. But don’t process everything for now, I have to resolve the problem of the documentation links resolution to navigate between the docs.

mithrendal commented 5 years ago

I only did exec.library again, slowly moving to perfection ... 😅

execV4.zip

if you are interested in the current state of the script ... getthedocs.py.zip

Tell me what you need next 😃...

prb28 commented 5 years ago

This version seems pretty good. I've figured how to handle the links in the documentation, so I've a little request. Could you change the links with a relative path to the other documentation page. As an example with two files in the same directory:

[OpenLibrary](/exec:OpenLibrary)

will become:

[OpenLibrary](OpenLibrary)

If they are in different directories:

[OpenLibrary](../exec/OpenLibrary)

If it's easier the second form with the path ../exec/OpenLibrary can be always used.

mithrendal commented 5 years ago

try this... execV5.zip

do you have an example where the doc jumps into different directories ?

prb28 commented 5 years ago

Thanks, this seems good! Here is the extension with docs so you can see the result of your work: amiga-assembly-0.17.0.vsix.zip

I do not have an example of a link in a different directory, so it may not exist! (maybe you'll found some...)

mithrendal commented 5 years ago

Wow, that is amazing cool ! It works. Je suis super content! 😊

There are still sometimes some lonely links to nowhere. Basically these are links not included in the main lib entries index. For example a link to a certain struct ... Of course our python program can be modified to also follow these type of links and download the referenced doc next to the referencing md file. As it looks I will do have a new tasks.

But this version is also really cool for me I think. 😉

Should we now already make the graphics,dos, intuition library docs? Or should we first teach the python script to read the missing doc files ?

prb28 commented 5 years ago

I think it's cool feature too. Well now, you're the main user, so choose what you think the goal for a first release is. This means what will meet your needs (and maybe @endo64 ), and I will do the release when ready.

mithrendal commented 5 years ago

I think to teach the python script to collect the additional docs is also not very difficult. The are several approaches to it fully recursive or not recursive, etc... At the moment I think, I will just refactor the script, so that it will additionally collect the links of a single doc file which are not already in the main "lib entries link list" and add process them afterwards in the same manner as each of the main lib entries. This way it should automatically take care of cross library references.

mithrendal commented 5 years ago

harder than I thought. I have it now that it collects the additional docs. But a remaining thing is that these docs are referenced to by multipe other docs under different names. As for now I worked with visible names only and removed the technical filenames urls (the thing in href=".."). But now it seems I have to rewrite the whole program in order that it uses these technical url-names when linking to the additional docs...

To get it solid I will need some days more than I thought.😀

prb28 commented 5 years ago

Looks like a highway to hell ;-)

mithrendal commented 5 years ago

It works now. But is no python script anymore. 😅 I will call it from now on no more only script. The script said to me I should call it python program from now on. 😂

The test run was fine on a selection of files. I think I have cracked it now. But I will do some more deeper checks on more docs tomorrow evening.

mithrendal commented 5 years ago

exec library docs, now updated with all links to structs and other non lib entry description files, which are also included now. Easy to see when you look at the docnames. Additional doc files have numbers as name. For example "0099.md". Can you exclude these extra files from VSCode code completion lookup ?

Now there should be no link anymore which leads to nowhere. At least I hope so. 😅

execV6.zip

mithrendal commented 5 years ago

Do you think it could already be prime time for the graphics library ?

This one uses a lot of additional structures, like viewport, rasport, colormap, bitmap ... It is also huge ...

graphicsV1.zip

A good test candidate.

mithrendal commented 5 years ago

I could also prefix the second level doc files with another char, for example with an underscore if it is easier for Amiga Assembly ...

for example _0099.md

It is also easy for me to collect the 3rd level doc files, these are files that are referenced by the second level doc files only. Do we want them too ? 🤔

prb28 commented 5 years ago

vscode does not seem to accepts the number in the links of hovers (popups). Do you have a way to rename them only with letters ? 0094.md -> OOID.md (I've added as you thought is the best way to filter them) These files are mainly C headers, could you add a code bloc link this ?

```c
\``` (>remove '\')

I found the vscode accepts some markdown from github. What do you think about a synopsis bloc with

```c
    AbortIO(iORequest)
            A1
    VOID AbortIO(struct IORequest *);
\``` (>remove '\')
Links: [IORequest](CODE_AAEF)

Result:

    AbortIO(iORequest)
            A1
    VOID AbortIO(struct IORequest *);

Links: IORequest

Do you think it could be done?

I don't know if the 3rd inclusion level is necessary do you have an example ?

Some sublinks are in different libraries: 014A.md -> dos.library/CreateProc it's a function from dos library. Should be ../dos/CreateProc. (If it's not easy it can stay like that).

mithrendal commented 5 years ago

Point 1: to decode the number into alphabetic filenames + prefix them with underscore is super easy. Point 2: additional files should start with a `c and end with. The c stands for code ? That is easy too. Point 3: easy to do when only one link in a code block. But what should the generator do if there are two links in a codeblock ? Answer: I think 3rd level docs are only detected by the generator if the 2nd level doc is not a header file but a link to a different library. Point 4: also on my todo list now. ;-) Especially "Point 2" is applicable on c header files only not on external library entries... So I will have to differentiate the type of the 2nd level doc anyway...

ce soir je vais voir dans cette matiere... ;-)

prb28 commented 5 years ago

Point 2: the c stands for language C, that why the colors are better suited. Point 3: With two links I think a list of links without separator could be good.

Bon courage !

mithrendal commented 5 years ago

Point1: accomplished. 😎 Point2: accomplished. 😎 Point3: accomplished. 😎 Point4: accomplished maybe. 🤕 different library detection needs some rework... I think..

execV7.zip

prb28 commented 5 years ago

Es ist fast fertig ! I saw two small points (keep on counting ;-)): Point5: There is a ````c bloc at the beginning of the files that is not useful Point6: It's missing a newline before the Function title Here is the resulting extension (exec is in v7 graphics is old) amiga-assembly-0.17.0.vsix.zip

mithrendal commented 5 years ago

Point5: accompli Point6: accompli

execV8.zip

But I will relook the Point4, I am not sure if it is done right... will check that now

prb28 / vscode-amiga-assembly

IntelliSense for commodore libraries #63