FB manual for Devhelp (LINUX)

Forum for discussion about the documentation project.
Post Reply
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

FB manual for Devhelp (LINUX)

Post by TJF »

Image

The FB manual is available for off-line usage as a .chm file. Chm readers can operate just one file. They cannot open two or more files at once.

When writing big projects this is an issue since you often need more than one documentation. One for FB and one for each library your code depends on. You might open two or more browsers with different manual files. But in this case you cannot use the context-sensitve help function in your IDE (or you have to do a lot of configuration work to choose the right instance for looking up the keyword).

A better choise is the GNOME reader Devhelp. It can find keywords in a bunch of manuals (called books). Each book is installed in a folder, several folders are stored in the devhelp directories.

The FB manual is now available as a Devhelp book:
Also available is the German 'Befehlsreferenz' for Devhelp (Stand 16.03.2012):

Installation (Debian)

To use these books you first need a Devhelp installation
  • sudo apt-get install devhelp
Then unpack the archive content to a Devhelp directory (folder 'freebasic_En' and / or 'freebasic_De'), either for local usage
  • ~/.devhelp/books
or for global usage (all users - root privileges required)
  • /usr/share/gtk-doc/html
After a restart of Devhelp you should have a new language 'Fbc' and one (or two) new book called 'FreeBASIC Manual' / 'FreeBASIC Anleitung'. You can use both books, the German and the English simultanously ; ). The screenshot lists some double entries because I've installed two books for GTK (for version 2 and for version 3).

The links inside the pages are still working like in the original .chm file. I added a new feature: the FB logo at the upper right corner on each page is a new link to the overview page (the one shown in the picture above).


Usage in Geany

For context-sensitive help in Geany IDE set a context-action in menu 'Preferences -> Tools: Context action:'
  • devhelp -s '%s'

When pressing the context-action key (defaults to F12) Geany should make Devhelp showing the page for the keyword under the Geany cursor. If Devhelp isn't running yet a new instance will previously be started. In this case devhelp searches case sensitive if any upper case character is included.

If you want to search case-insensitive you have to convert the keyword to lower case characters. I use this script

Code: Select all

#! /bin/bash
# Startet devhelp

devhelp -s $(echo $@ | sed 's/[[:upper:]]/\L&/g')
It's called "calldevhelp", so the context command in Geany is
  • calldevhelp '%s'
Have fun!


Edit:
Updates to fbc 0.24, 0.90.1
Last edited by TJF on Nov 13, 2013 12:08, edited 2 times in total.
AGS
Posts: 1284
Joined: Sep 25, 2007 0:26
Location: the Netherlands

Post by AGS »

If you want to add the api of a library then there must be some way to turn .bi files into .xml files. Those .bi files have to be 'parsed' and turned into xml. Any info on usage of a library has to be in the .bi file or devhelp will be less helpful.

Supposing those .bi files are created from .h files (assuming api of some external library). Those .h files will contain 'free format' documentation or, if you are lucky, documentation in the doxygen format (or some other known format).

If the sources are known to be documented using a certain documentation format a parser could use that info to create a suitable devhelp xml file. If there is no such info then I can still see how devhelp could be used but it's helpfulness would be somewhat less.

Have you had any success trying to get from .h to .bi to .xml? .h to .bi should work (h2bi works). It's that final step that could prove to be difficult.

I found a devhelp - plugin for geany (don't know if it's up to date):
http://plugins.geany.org/devhelp.html

Pity devhelp is not available on win32 yet as I would sure like to use it.
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

Re: FB manual for Devhelp (LINUX)

Post by TJF »

Hi AGS, why aren't you sleeping at 4 am?
AGS wrote:Pity devhelp is not available on win32 yet as I would sure like to use it.
I think they wont port it. There're no development activities since years. But I like Devhelp as it is, limited to the basics. I just added a keyboard shortcut to set the cursor in the entry field.
AGS wrote:I found a devhelp - plugin for geany (don't know if it's up to date):
AFAIK it's up-to-date. But I don't like it. It uses libdevhelp to open a help tag in the notebook where the code is shown. That's good if you have just one source file in your project. But if you have more source files it's hard to find the way back from the help tag. It's much easier to use <alt>+<tab> to swap between two apps.
AGS wrote:Have you had any success trying to get from .h to .bi to .xml? .h to .bi should work (h2bi works). It's that final step that could prove to be difficult.
  • From .h to .xml there's the native solution gtk-doc.
  • From .h to .bi isn't necessary if you have the API-doc-book. Nobody will look in a .bi file if he can browse better information in a .html including images.
  • The final step from .bi to .xml/.html might be interesting to document FB software/libraries. (Nothing available yet, AFAIK.)
marcov
Posts: 3455
Joined: Jun 16, 2005 9:45
Location: Netherlands
Contact:

Re: FB manual for Devhelp (LINUX)

Post by marcov »

Strange, with kchmviewer this worked fine for me (links between CHMs).

If you use kchmviewer, please test with different backends. (there is a webkit and an older rendering backend). It does load it in the same context, but the back button worked fine.

If you used gnochm, I agree it is utterly unusable :-)
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

Re: FB manual for Devhelp (LINUX)

Post by TJF »

marcov wrote:Strange, with kchmviewer this worked fine for me (links between CHMs).
I used kchmviewer in the past. It can link between .chm files. But it cannot link between .chm and .html files (ie FB manual and cairo-API-docs). It doesn't seach for a keyword in all documents, it just searches in the currently loaded one.

kchmviewer isn't very stabil. (Did you try a search without loading a file before?)

And kchmviewer has another downside. When calling it directly from the command line (or in Geany) it opens a new instance on each call. To avoid that you have to call the dbus methods, but by default this wont open a new instance in case kchmviewer isn't running. So you have to install the dbus service first (the installer wont do this). A lot of work for just a partial solution.

That's why I ported the FB manual to Devhelp and share it here : )


BTW: I think the manual should be shipped with the compiler.
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

Re: FB manual for Devhelp (LINUX)

Post by TJF »

Up-dated to version 0.90.1, smaller tar.bz2 file now:
AGS
Posts: 1284
Joined: Sep 25, 2007 0:26
Location: the Netherlands

Re: FB manual for Devhelp (LINUX)

Post by AGS »

Using your archive I created an EPUB version of the manual.
I used SIGIL to create the epub. I simply unpacked
the .bz2 file, imported the images, html files, cascading
style sheet and was nearly done (some links did not work).

Here is a link to the epub.
http://www.sarmardar.nl/FreeBASIC/fb_manual.epub

The epub needs a bit of updating here and there. The html
pages could be sequenced a bit better. And I was having trouble
getting the index to work in combination with the e book viewer
I use (the calibre built-in e book viewer). I don't know what the
problem is but an epub without a proper index isn't good enough.

Searching inside the epub works remarkably well.
When you search for a keyword (starting the search from the
top of the epub) you almost always (if not always)
get a hit in the full index (the full index starts at the
second page of the epub). Which means you can find the page
associated with a keyword very fast.

Thanks for the archive (it made creation of the epub a lot easier).
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

Re: FB manual for Devhelp (LINUX)

Post by TJF »

AGS wrote:Thanks for the archive (it made creation of the epub a lot easier).
You're welcome!

I use a (quick and dirty) tool to
  • collect the index entries from all pages
  • add the link under the logo at each page and
  • output the index file.
Maybe it can get addapted to create the epub directly?

Code: Select all

#DEFINE TOCDOC """00index.html"""
#DEFINE TOCVER " name=""FB-manual-0.90.1"""

FUNCTION get_title(BYREF n AS STRING, BYREF t AS STRING) AS STRING
  'STATIC AS ZSTRING ptr s1 = @"<title>", s2 = @"</title>"
  STATIC AS ZSTRING PTR s1 = @"<div id=""fb_tab_l"">", s2 = @"</div>"
  STATIC AS ZSTRING PTR s3 = @"&nbsp;<img src=""images/fblogo_mini.gif"" /></div>"
  VAR p = 0, a = 0, l = 0, i = 0, z = LEN(t) - 1
  FOR a = 0 TO z
    IF t[a] <> s1[p] THEN p = 0 ELSE p += 1 : IF s1[p] = 0 THEN EXIT FOR
  NEXT : p = 0
  FOR i = a + 1 TO z
    IF t[i] <> s2[p] THEN p = 0 ELSE p += 1 : IF s2[p] = 0 THEN l = i - p - a : a += 2 : EXIT FOR
  NEXT : p = 0
  FOR i = i + 1 TO z
    IF t[i] <> s3[p] THEN p = 0 ELSE p += 1 : IF s3[p] = 0 THEN EXIT FOR
  NEXT
  IF s3[p] = 0 THEN
    VAR fnr = FREEFILE
    IF OPEN(n, FOR OUTPUT, ACCESS WRITE, AS #fnr) THEN
      ?"IO error: cannot overwrite file "; n
    ELSE
      p = i - p + 7 : i -= 4
      PRINT #fnr, LEFT(t, p);
      PRINT #fnr, "<a href=" & TOCDOC & ">";
      PRINT #fnr, MID(t, p + 1, i - p - 1);
      PRINT #fnr, "</a>";
      PRINT #fnr, MID(t, i);
      CLOSE #fnr
    END IF
  END IF
  IF l THEN RETURN TRIM(MID(t, a, l), ANY !"\n\l\v\t ")
  RETURN ""
END FUNCTION

VAR fdir = "freebasic_En"
CHDIR("../" & fdir)
VAR n = DIR("*.html"),  _O_ = ""
WHILE LEN(n)
  VAR fnr = FREEFILE
  IF OPEN(n, FOR BINARY, ACCESS READ, AS #fnr) THEN
    ?"IO error: cannot read file "; n
  ELSE
    VAR l = LOF(fnr), c = STRING(l, 0)
    GET #fnr, , c
    CLOSE #fnr
    _O_ &= "  <function link=""" & n & """ name=""" & get_title(n, c) & !"""/>\n"
  END IF
  n = DIR()
WEND

n = fdir & ".devhelp"
VAR fnr = FREEFILE
IF OPEN(n, FOR OUTPUT, ACCESS WRITE, AS #fnr) THEN
  ?"IO error: cannot write file "; n
ELSE
  PRINT #fnr, "<?xml version=""1.0"" encoding=""utf-8""?>"
  PRINT #fnr, "<book link=" & TOCDOC & TOCVER & " title=""FreeBASIC Manual"" language=""fbc"">"
  PRINT #fnr, " <functions>"
  PRINT #fnr, _O_;
  PRINT #fnr, " </functions>"
  PRINT #fnr, "</book>"
  CLOSE #fnr
END IF
AGS
Posts: 1284
Joined: Sep 25, 2007 0:26
Location: the Netherlands

Re: FB manual for Devhelp (LINUX)

Post by AGS »

Thanks for the code, TJF. I have added an index to the epub
that works with the calibre viewer. I'm going to extend the index
a bit so it looks (almost) like the one you get with the official
compiled html file. After extending the index I'll release the
epub 'officially' (put it up for download in the community thread).
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

FB manual for Devhelp (LINUX): update 1.00.0.rc1 (140911)

Post by TJF »

New release
The new script calldevhelp can be used to pass the context in lower case letters. That makes DevHelp searching the keywords non-case-sensitve (even if the original context contained upper-case-letters).
TJF
Posts: 3809
Joined: Dec 06, 2009 22:27
Location: N47°, E15°
Contact:

Re: FB manual for Devhelp (LINUX)

Post by TJF »

This project is obsolete now.

The successor project is viewtopic.php?f=8&t=29629
pointing to the new source hosting at https://github.com/DTJF/fb_devhelp
Post Reply