From 745828154547e0dbd635afb9fae469eac37a255a Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Mon, 10 Dec 2018 16:50:56 +0100 Subject: Rename README files to README.txt (and several similar files). Files without '.txt' suffix can't be handled well by Windows (users), hence renaming such text files to *.txt makes FLTK more "Windows-friendly". There are a few exceptions (this is intentional): README and other files in bundled libraries (maintained upstream) are not changed. --- documentation/README | 108 ------------------------------------------ documentation/README.txt | 112 ++++++++++++++++++++++++++++++++++++++++++++ documentation/src/intro.dox | 63 ++++++++++++------------- 3 files changed, 141 insertions(+), 142 deletions(-) delete mode 100644 documentation/README create mode 100644 documentation/README.txt (limited to 'documentation') diff --git a/documentation/README b/documentation/README deleted file mode 100644 index 7fa1151e9..000000000 --- a/documentation/README +++ /dev/null @@ -1,108 +0,0 @@ -README (documentation) ----------------------- -FLTK 1.3 (and higher) documentation is available in HTML and PDF format. -The documentation must be generated in a separate step or downloaded -from FLTK's software download pages. The documentation can also -be accessed online. - -To read the docs after downloading or generating them, open the -files: - - documentation/html/index.html - documentation/fltk.pdf - -with your browser or PDF viewer, respectively. - - -Online Documentation: ---------------------- -A documentation version is available online at the FLTK web site, -along with the PDF version of the manual. The docs on the web site -are usually somewhat older (latest release). Use this URL to find -the current online documentation: - - http://www.fltk.org/documentation.php - - -Documentation Download: ------------------------ -To download pre-generated docs, go to - - http://www.fltk.org/software.php - -and look for the files - - fltk--docs-html.tar.gz - fltk--docs-pdf.tar.gz - -Extract the documentation tarballs into the same directory as you -did with the source tarball. - - -Generation of Documentation (common part): ------------------------------------------- -To generate the documentation yourself, you should have Doxygen -version 1.5.7 or later (recommended version is 1.7.3 or later). - -To generate the PDF version you also need a current version of LaTeX. -You can use the packages tetex (older) or texlive (current) if your -distribution provides them. You may need to install additional fonts -and other sub-packages for the PDF version to be generated correctly. - - -Generation of Documentation with autoconf (configure) + make: -------------------------------------------------------------- -Use "make html" in the documentation directory to generate the HTML -documentation, or "make pdf" to generate the PDF version. "make docs" -generates both versions in one step (as would do "make clean html pdf"). - -To read the HTML or PDF docs, see above. - - -Generation of Documentation with CMake + make: ----------------------------------------------- -We assume that you use an out-of-source build as recommended. -Documentation is not generated in a default build. You must set one or -more CMake options using cmake-gui, ccmake, or cmake -DOPTION... - -These options are predefined to OFF and can be switched ON: - - - OPTION_BUILD_HTML_DOCUMENTATION:BOOL=OFF target: html - - OPTION_BUILD_PDF_DOCUMENTATION:BOOL=OFF target: pdf - - - OPTION_INSTALL_HTML_DOCUMENTATION:BOOL=OFF - - OPTION_INSTALL_PDF_DOCUMENTATION:BOOL=OFF - -If you switch one or both of the first two options ON, then the -targets 'html' and/or 'pdf' are generated, respectively. Target 'docs' -is added to generate both 'html' and 'pdf'. As said above, you need -installed Doxygen and LaTeX software for this to work. - -Use "make html" in the root or documentation directory of the build tree -to generate the HTML documentation, or "make pdf" to generate the PDF -version. "make docs" generates both versions in one step (as would do -"make clean html pdf"). - -To read the HTML or PDF docs, see above, but use the build directory. - -Note: if you enable one or more of the "*INSTALL*" options, then -`make install' will install the docs, but you must still build them -manually, because the generation is not included in the standard ('all') -target. This may be changed in the future. - - -FLTK Developer Snapshots or Subversion Usage: ---------------------------------------------- -There is no pre-generated documentation available if you use a current -developer snapshot or subversion. You must generate the documentation -yourself or access the online documentation. - - -Bugs and Feature Requests: --------------------------- -If you find any typos, things that are unclear, or would like to -contribute an example, section, or chapter to the FLTK manual, please -post a question in the fltk newsgroup fltk.general or post a bug -report or feature request at: - - http://www.fltk.org/str.php diff --git a/documentation/README.txt b/documentation/README.txt new file mode 100644 index 000000000..6b7e39980 --- /dev/null +++ b/documentation/README.txt @@ -0,0 +1,112 @@ +README.txt (documentation) +--------------------------- +FLTK 1.3 (and higher) documentation is available in HTML and PDF format. +The documentation must be generated in a separate step or downloaded +from FLTK's software download pages. The documentation can also +be accessed online. + +To read the docs after downloading or generating them, open the files: + + documentation/html/index.html + documentation/fltk.pdf + +with your browser or PDF viewer, respectively. + + +Online Documentation: +--------------------- +A documentation version is available online at the FLTK web site, +along with the PDF version of the manual. The docs on the web site +are usually somewhat older (latest release). Use this URL to find +the current online documentation: + + https://www.fltk.org/documentation.php + + +Documentation Download: +----------------------- +To download pre-generated docs, go to + + https://www.fltk.org/software.php + +and look for the files + + fltk--docs-html.tar.gz + fltk--docs-pdf.tar.gz + +Extract the documentation tarballs into the same directory as you +did with the source tarball. + + +Generation of Documentation (common part): +------------------------------------------ +To generate the documentation yourself, you should have Doxygen +version 1.8 or later (recommended version is 1.8.13 or later). +Older Doxygen versions than 1.8 may or may not work. + +To generate the PDF version you also need a current version of LaTeX. +You can use the packages tetex (older) or texlive (current) if your +distribution provides them. You may need to install additional fonts +and other sub-packages for the PDF version to be generated correctly. + +Note: packages known to work under Ubuntu 18.04: + + texlive texlive-extra-utils texlive-latex-extra texlive-font-utils + + +Generation of Documentation with autoconf (configure) + make: +------------------------------------------------------------- +Use "make html" in the documentation directory to generate the HTML +documentation, or "make pdf" to generate the PDF version. "make docs" +generates both versions in one step (as would do "make clean html pdf"). + +To read the HTML or PDF docs, see above. + + +Generation of Documentation with CMake + make: +---------------------------------------------- +We assume that you use an out-of-source build as recommended. +Documentation is not generated in a default build. You must set one or +more CMake options using cmake-gui, ccmake, or cmake -DOPTION... + +These options are predefined to OFF and can be switched ON: + + - OPTION_BUILD_HTML_DOCUMENTATION:BOOL=OFF target: html + - OPTION_BUILD_PDF_DOCUMENTATION:BOOL=OFF target: pdf + + - OPTION_INSTALL_HTML_DOCUMENTATION:BOOL=OFF + - OPTION_INSTALL_PDF_DOCUMENTATION:BOOL=OFF + +If you switch one or both of the first two options ON, then the +targets 'html' and/or 'pdf' are generated, respectively. Target 'docs' +is added to generate both 'html' and 'pdf'. As said above, you need +installed Doxygen and LaTeX software for this to work. + +Use "make html" in the root or documentation directory of the build tree +to generate the HTML documentation, or "make pdf" to generate the PDF +version. "make docs" generates both versions in one step (as would do +"make clean html pdf"). + +To read the HTML or PDF docs, see above, but use the build directory. + +Note: if you enable one or more of the "*INSTALL*" options, then +`make install' will install the docs, but you must still build them +manually, because the generation is not included in the standard ('all') +target. This may be changed in the future. + + +FLTK Developer Snapshots or Git Usage: +-------------------------------------- +There is no pre-generated documentation available if you use a current +developer snapshot or git. You must generate the documentation +yourself or access the online documentation. + + +Bugs and Feature Requests: +-------------------------- +If you find any typos, things that are unclear, or would like to +contribute an example, section, or chapter to the FLTK manual, please +post a question in the fltk newsgroup fltk.general or post a bug +report or feature request at: + + https://www.fltk.org/str.php diff --git a/documentation/src/intro.dox b/documentation/src/intro.dox index cfb7d1c10..7213fbba5 100644 --- a/documentation/src/intro.dox +++ b/documentation/src/intro.dox @@ -5,7 +5,7 @@ The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a cross-platform C++ GUI toolkit for UNIX®/Linux® (X11), Microsoft® Windows®, and -Apple® OS X®. FLTK provides modern GUI functionality without the +Apple® macOS®. FLTK provides modern GUI functionality without the bloat and supports 3D graphics via OpenGL® and its built-in GLUT emulation. It was originally developed by Mr. Bill Spitzak and is currently maintained by a small group of developers @@ -143,13 +143,10 @@ the toolkit, which was already in use by several people, Bill came up with "FLTK", including a bogus excuse that it stands for "The Fast Light Toolkit". -\section intro_unix Building and Installing FLTK Under UNIX and Apple OS X +\section intro_unix Building and Installing FLTK Under UNIX and Apple macOS -In most cases you can just type "make". This will -run configure with the default of no options and then compile -everything. - -For OS X, Xcode 3 project files can be found in the 'ide' directory. +In most cases you can just type "make". This will run configure with +the default of no options and then compile everything. FLTK uses GNU autoconf to configure itself for your UNIX platform. The main things that the configure script will look @@ -268,37 +265,34 @@ with object files from any of the other environments! (They use incompatible C++ conventions internally.) Free Microsoft Visual C++ 2008 Express and Visual C++ 2010 Express -or later versions using the supplied workspace and -project files. Older versions, and the commercial -versions, can be used as well, if they can open -the project files. +or later versions using workspace and project files generated by CMake. +Older versions and the commercial versions can be used as well, if they +can open the project files. Be sure to get your service packs! -The project files can be found in the "ide/" directory. -Please read "ide/README.IDE" for more info about this. +Since FLTK 1.4 the project files MUST be generated with CMake. +Please read "README.CMake.txt" for more information about this. \subsection intro_cygwin_mingw GNU toolsets (Cygwin or MinGW) hosted on Windows -If using Cygwin with the Cygwin shell, or MinGW with -the Msys shell, these build environments behave very -much like a Unix or OS X build and the notes above in -the section on -Building and Installing FLTK Under UNIX and Apple OS X +If using Cygwin with the Cygwin shell, or MinGW with the Msys shell, +these build environments behave very much like a Unix or macOS build +and the notes above in the section on +Building and Installing FLTK Under UNIX and Apple macOS apply, in particular the descriptions of using the "configure" script and its related options. -In general for a build using these tools, e.g. for -the Msys shell with MinGW, -it should suffice to "cd" into the directory where -you have extracted the fltk tarball and type: +In general for a build using these tools, e.g. for the Msys shell with +MinGW, it should suffice to "cd" into the directory where you have +extracted the FLTK tarball and type: \code ./configure make \endcode -This will build the fltk libraries and they can then be +This will build the FLTK libraries and they can then be utilised directly from the build location. NOTE: this may be simpler than "installing" them in many cases as different tool chains on Windows have @@ -319,7 +313,7 @@ something like "C:\msys\1.0\local\lib", depending on where your Msys installation is rooted, which may not be useful to other tools. -If you want to install your built fltk libraries in a +If you want to install your built FLTK libraries in a non-standard location you may do: \code @@ -328,10 +322,10 @@ make \endcode Where the value passed to "prefix" is the path at which -you would like fltk to be installed. +you would like FLTK to be installed. A subsequent invocation of "make install" will then place -the fltk libraries and header files into that path. +the FLTK libraries and header files into that path. The other options to "configure" may also be used to tailor the build to suit your environment. @@ -354,28 +348,29 @@ header files. FLTK is available on the 'net in a bunch of locations: \par WWW -http://www.fltk.org/
-http://www.fltk.org/str.php [for reporting bugs]
-http://www.fltk.org/software.php [source code]
-http://www.fltk.org/newsgroups.php [newsgroup/forums] +https://www.fltk.org/
+https://www.fltk.org/str.php [for reporting bugs]
+https://www.fltk.org/software.php [download source code]
+https://www.fltk.org/newsgroups.php [newsgroup/forums] \par NNTP Newsgroups https://groups.google.com/forum/#!forum/fltkgeneral [Google Groups interface] news://fltk.org:1024/ [NNTP interface]
-http://fltk.org/newsgroups.php [web interface]
+https://www.fltk.org/newsgroups.php [web interface]
\section intro_reporting Reporting Bugs To report a bug in FLTK, or for feature requests, please use the form at -http://www.fltk.org/str.php, +https://www.fltk.org/str.php, and click on "Submit Bug or Feature Request". You'll be prompted for the FLTK version, operating system & version, and compiler that you are using. We will be unable to provide any kind of help without that basic information. -For general support and questions, please use the fltk.general newsgroup (see above, "NNTP Newsgroups") -or the web interface to the newsgroups at http://fltk.org/newsgroups.php. +For general support and questions, please use the fltk.general newsgroup +(see above, "NNTP Newsgroups") or the web interface to the newsgroups at +https://www.fltk.org/newsgroups.php. \htmlonly
-- cgit v1.2.3