fbdoc - FreeBASIC User's Manual Converter/Generator
  Copyright (C) 2006-2020 The FreeBASIC development team.

License:

  This program is free software; you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2 of the License, or (at your option) any later 
  version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
  Street, Fifth Floor, Boston, MA 02111-1301 USA.


Purpose of fbdoc:

  The main purpose of fbdoc is for the conversion and generation of the 
  FreeBASIC manual from https://www.freebasic.net/wiki to other formats.
  Secondary to this purpose is the creation of tools that will help
  maintain or format the wakka script located online.

  fbdoc is built both as an executable application and as a library.  The
  executable application is used for the actual document conversion and
  generation.  The library and headers are used for other tools that
  might help in the development and maintenance of the online manual.

  No real concern is made at the moment for backwards compatibility where
  fbdoc is used as a library since there are relatively few users of fbdoc
  as an application, and even fewer that use it as a library. This might
  change in future, but for now, the focus is on supporting the maintenance
  conversion and generation of the FreeBASIC manuaul.

  There will likely never be a binary distribution of fbdoc. It is built 
  from sources.  The doc converter is modified as needed to build the
  the on-line docs.

  Finally, aside from the FreeBASIC compiler itself, fbdoc serves as a test
  application written in FreeBASIC that helps to test making practical use 
  of the language itself.  While fbdoc does not test every feature available 
  in the FreeBASIC language, fbdoc is a non-trivial application that must 
  continue to work for years to come.


Compiling:

  Type in a command prompt in the fbdoc directory:
    $ make
  This will generate the "fbdoc" executable.

  o Requirements:

    - FreeBASIC Compiler version 1.04.0 or greater and compatible build 
      environment.
    - Windows or Linux OS (DOS not supported)
    - pcre
    - libcurl
    - internet connection ( optional, to download wiki pages not in git
	  repository )
    - make


Running:

  o First time use:

    - type "fbdoc -help" for a list of options

    - In the directory where fbdoc executable was made, type "fbdoc -makeini"
      and this will create a default "fbdoc.ini".  Edit the file to configure
      connection settings.  However, this step is not required if building
      from git repository only.


  o Building the CHM from Git Repository:

    - In the directory where fbdoc executable was made, 
      type "fbdoc -usecache -chm"

    - When the process is complete, use html help compiler to make the CHM 
      using ./html/fbdoc.hhp as the project file.


  o Building the CHM from the wiki over the web:

    - In the directory where fbdoc executable was made, 
      type "fbdoc -useweb -chm"

    - When the process is complete, use html help compiler to make the CHM 
      using ../manual/html/fbdoc.hhp as the project file.


  o Building the CHM using an MySQL Database source:

    - fbdoc must be compiled with HAVE_MYSQL=1 option passed to make.

    - Edit "fbdoc.ini" to set the host name or ip address, user name, 
      password, database name, and port number to use for the MySQL 
      database connection. 

    - In the directory where the fbdoc executable was made, 
      type "fbdoc -usesql -chm"

    - When the process is complete, use html help compiler to make the CHM
      using ../manual/html/fbdoc.hhp as the project file.


  o Building the FBHELP.DAT format using the existing cache:

    - assuming that the cache is already filled, for example by previously
      making the CHM, additional formats can be generated by using the
      existing local cache only

    - type "fbdoc -usecache -fbhelp"

    - type "mkfbhelpfile"
      this will generate fbhelp.dat in the fbhelp folder.


  o Forcing a refresh of the cache and building multiple formats:

    - type "fbdoc -refresh -useweb -chm -fbhelp -txt"


Credits:

  o Jeffery R. Marshall (coder[at]execulink.com):
    - main developer of fbdoc application

  o Andre Victor T. Vicentini (av1ctor[at]yahoo.com.br):
    - Created backend code for using PCRE and libCURL.
    - Ported the first version of the Wikka parser code from PHP 
      sources to FreeBASIC.
    - created list.bas and list.bi - a generic linked list


Links:

  o Official site: https://www.freebasic.net/

  o External libraries:

    - Curl: https://curl.haxx.se/

    - MySQL: https://dev.mysql.com/

    - PCRE: http://www.pcre.org/
    


EOF