[bmx] Online doc links by markcw [ 1+ years ago ]

Started by BlitzBot, June 29, 2017, 00:28:38

Previous topic - Next topic

BlitzBot

Title : Online doc links
Author : markcw
Posted : 1+ years ago

Description : This adds links to the Brl and Pub module docs. It is to make it quicker to look up the BlitzMax online manual.

Obviously doing a Rebuild docs will remove the links again.

Also, it won't add a link if there is one there already and you can run the source file from anywhere under the BlitzMax directory.

It is cross-platform and depending on the way your IDE works, the links will either open in the default browser or directly.

Edit: updated to work as a type.


Code :
Code (blitzmax) Select
' Online doc links.bmx
'
' Adds links to docs/html for all functions in brl and pub modules, links are to online doc

SuperStrict

Local p:AddDocLinks = New AddDocLinks

p.FindFiles(p.FindDocs())

End

Type AddDocLinks
Field mdir$=FindDocs()

Method FindDocs$()
Local wdir$=CurrentDir()+"/" ' find the docs
Local ldir$=wdir.Tolower() ' lowercase
Local bms%=ldir.Find("blitzmax",0) ' bmax start
If bms=-1 RuntimeError "Failed to find blitzmax directory"

Local bme%=ldir.Find("/",bms) ' bmax end
Return wdir[..bme]+"/docs/html/Modules" ' modules dir
End Method

Method FindFiles(dir$)
Local dh%=ReadDir(dir)
If Not dh RuntimeError "failed to read current directory"

Repeat
Local temp$=NextFile(dh)
If temp="" Then Exit ' done
If temp="." Or temp=".." Continue ' skip
Local cfile$=dir+"/"+temp ' current file
If FileType(cfile)=2 Then FindFiles2(cfile) ' directory
Forever

CloseDir dh
End Method

Method FindFiles2(dir$)
Local dh%=ReadDir(dir)
If Not dh RuntimeError "failed to read current directory l2"

Repeat
Local temp$=NextFile(dh)
If temp="" Then Exit ' done
If temp="." Or temp=".." Continue ' skip
Local cfile$=dir+"/"+temp ' current file
If FileType(cfile)=2 Then FindFiles3(cfile) ' directory
Forever

CloseDir dh
End Method

Method FindFiles3(dir$)
Local dh%=ReadDir(dir)
If Not dh RuntimeError "failed to read current directory l3"

Repeat
Local temp$=NextFile(dh)
If temp="" Then Exit ' done
If temp="." Or temp=".." Continue ' skip
Local cfile$=dir+"/"+temp ' current file
If FileType(cfile)=1 ' file, html
If ExtractExt(cfile)="html" Then OpenHtml(cfile)
EndIf
Forever

CloseDir dh
End Method

Method OpenHtml(path$)

Local html$,file:TStream=OpenFile(path)
If Not file RuntimeError "could not open file"

While Not Eof(file)
html=ReadString(file,FileSize(path))
Local html2$,link$,lpart$
Local fr%=html.Find("Function reference",0)
Local fts%=fr,fbs%,fen%,fte%,fbe%

If fr>0 ' file has functions
html2=html
Print "Adding Links: "+path[mdir.length+1..path.Find("index.html",mdir.length)-1]

While fts>-1 ' while functions in file
fts=html.Find("colspan=2>Function ",fts+1)
If fts>0
fts:+19 ' to function name
fbs=html.Find("(",fts) ' bracket start
fte=html.Find("</td>",fts) ' table end
fen=html[fts..fbs].Find(":",0) ' type (end of func name)
If fen>0 Then fbs=fts+fen
fen=html[fts..fbs].Find("[",0) ' array
If fen>0 Then fbs=fts+fen
fen=html[fts..fbs].Find("$",0) ' string
If fen>0 Then fbs=fts+fen
fen=html[fts..fbs].Find("#",0) ' float
If fen>0 Then fbs=fts+fen
fen=html[fts..fbs].Find("!",0) ' double
If fen>0 Then fbs=fts+fen
fen=html[fts..fbs].Find("_",0)

If fen=-1 ' not a lua_func
fen=html[fts..fbs].Find(" ",0) ' trim spaces
If fen>0 Then fbs=fts+fen
Local func$=html[fts..fbs] ' get func name
fbe=html[fts..fte].Find("NoDebug",0) ' bracket end or nodebug
If fbe=-1 Then fbe=html[fts..fte].FindLast(")",0) Else fbe:+6
fbe:+fts+1
link=html[fbe..fte] ' leave existing links alone
lpart=" [<a href="+Chr(34)+"http://www.blitzmax.com/bmdocs/command.php?name="
If fte-fbe=0
link=lpart+func+"&ref=goto"+Chr(34)+">Online doc</a>]" ' if no link add one
EndIf
html2=html[..fbe]+link+html[fte..]
EndIf
EndIf
html=html2 ' update html
Wend

EndIf
Wend

SeekStream file,0 ' overwrite file
WriteString file,html
CloseStream file

End Method

End Type


Comments :


degac(Posted 1+ years ago)

 Well, not to all commands I think (look for AllocUserEventID for example!)It seems that online doc are not up to date with the one in the source code.


degac(Posted 1+ years ago)

 As you seem interested in working on documentation (I just see some other posts) an idea could be to do the inverse.*Look at the online documentation for each command*Download the page*Check if there are examples in the post (it should be the CODE/CODEBOX tag)*Save the content of the tags on the computer...I know this could be useless (if I have the link in my doc, just click on it to have the on line version and see other examples).But you could not be on internet... and examples - usually - needs when you cant' access internet!ps: idea2. You could change DocMods to create documentation+your link every time the user rebuild documentation. In the SRC folder there is the source code !EDIT: now the program/source is called MakeDocs (or something!)


markcw(Posted 1+ years ago)

 I did actually email Brl support about the missing functions and they said they would update these soon:In brl.Polledinput:MouseXSpeed, MouseYSpeed, MouseZSpeed.Also in brl.Event:EmitEvent, CreateEvent, AllocUserEventId.In brl.System:DesktopWidth, DesktopHeight, DesktopDepth, DesktopHertz.In brl.Max2d:SetVirtualResolution, VirtualResolutionWidth, VirtualResolutionHeight, VirtualMouseX, VirtualMouseY, VirtualMouseXSpeed, VirtualMouseYSpeed, MoveVirtualMouse.All of these were fairly recent additions in versions.txt but there may be some more.


degac(Posted 1+ years ago)

 I m happy to know this!


markcw(Posted 1+ years ago)

 I just found quite a few more missing entries and have emailed Brl support about it again. Here is a copy of the list:In Brl.D3D9Max2D:D3D9Max2DDriverIn Maxgui.ProxyGadgets:CreateHyperlink, CreateSplitter, SplitterPanel, SetSplitterPosition, SplitterPosition, SetSplitterOrientation, SplitterOrientation, SetSplitterBehavior, SplitterBehavior, CreateScrollPanel, ScrollPanelClient, FitScrollPanelClient, ScrollScrollPanel, ScrollPanelX, ScrollPanelYIn Maxgui.Localization:CreateLanguage, LoadLanguage, SaveLanguage, SetLanguageName, LanguageName, DefineLanguageToken, LanguageTokenDefinition, RemoveLanguageToken, ClearLanguageTokens, LocalizeString, SetLocalizationMode, LocalizationMode, SetLocalizationLanguage, LocalizationLanguageIn Brl.Threads:CreateThread, MainThread, CurrentThread, DetachThread, WaitThread, ThreadRunning, CreateThreadData, SetThreadDataValue, GetThreadDataValue, CreateMutex, CloseMutex, LockMutex, TryLockMutex, UnlockMutex, CreateSemaphore, CloseSemaphore, WaitSemaphore, PostSemaphore, CreateCondVar, CloseCondVar, WaitCondVar, SignalCondVar, BroadcastCondVar, CompareAndSwap, AtomicAdd, AtomicSwap


markcw(Posted 1+ years ago)

 In reply to your suggestions, I am intending to do something like that. Just to grab the code examples and build it into the offline docs and create files in the right place. Also, I hadn't thought of getting docmods/makedocs to run my code. I haven't really thought about editing makedocs yet. I'm just working on things I want to see, mainly I want to write a code highlighter. I "tweaked" makedocs before so I'll revisit that and see about getting a patch for it so all these things can happen on a "Rebuild docs".