Merge branch 'develop'

Author: robhagemans

BUILD.md

@@ -1,28 +1,31 @@
 
 
 ### Setting up a development environment for PC-BASIC
-These instructions cover the steps needed to install the development source of PC-BASIC and its dependencies. You can also follow them if you simply want to install PC-BASIC from the source repository on GitHub.
+These instructions cover the steps needed to install the development source of PC-BASIC and its dependencies.
 
-#### You won't need to read this file just to install PC-BASIC ####
-General installation instructions for PC-BASIC can be found in `README.md`.
-The instructions there cover the most common platforms and use cases.
+> #### You won't need to read this file just to install PC-BASIC ####
+> General installation instructions for PC-BASIC can be found in `README.md`.
+> The instructions there cover the most common platforms and use cases.
+> The instructions in this file are for developers only.
 
 
 #### Dependencies ####
 The following packages are needed, recommended or optional when installing PC-BASIC:
 
-| Package                                                                       | OS                 | Status       | Used for
-|-------------------------------------------------------------------------------|--------------------|--------------|----------------------------------------
-| [Python 3.6.9 or later](https://www.python.org/downloads/)                    | all                | required     |
-| [SDL2](https://www.libsdl.org/download-2.0.php)                               | all                | recommended  | graphics and sound with `--interface=graphical`
-| [PySerial 3.4](https://github.com/pyserial/pyserial)                          | all                | optional     | physical or emulated serial port access
-| [PyParallel](https://github.com/pyserial/pyparallel)                          | Windows, Linux     | optional     | physical parallel port access
-| [PyAudio](http://people.csail.mit.edu/hubert/pyaudio/)                        | all                | optional     | sound without SDL2
+| Package                                                                       | Status                     | Used for
+|-------------------------------------------------------------------------------|----------------------------|----------------------------------------
+| [Python 3.6.9 or later](https://www.python.org/downloads/)                    | required                   |
+| [`importlib_resources`](https://pypi.python.org/pypi/importlib_resources)     | required for Python <= 3.6 |
+| [SDL2](https://www.libsdl.org/download-2.0.php)                               | recommended                | graphics and sound
+| [PySerial 3.4](https://github.com/pyserial/pyserial)                          | optional                   | physical or emulated serial port access
+| [PyParallel](https://github.com/pyserial/pyparallel)                          | optional                   | physical parallel port access
+| [PyAudio](http://people.csail.mit.edu/hubert/pyaudio/)                        | optional                   | sound without SDL2
 
-`setuptools` and `pip` are included with Python.
 Once you have a working Python installation, most dependencies can be installed with `pip`:
 
-        pip3 install pysdl2-dll pyserial
+        pip install pysdl2-dll pyserial
+
+If `pip` is not included with your copy of Python, install it with `python -m ensurepip` or through your system's package manager.
 
 For Windows, Mac, and Linux, it is recommended to use the SDL2 and SDL2-gfx libraries provided by the [pysdl2-dll](https://github.com/a-hurst/pysdl2-dll) package.
 Alternatively, you can get the library directly from [libsdl.org](https://www.libsdl.org/download-2.0.php).
@@ -64,7 +67,7 @@ The following additional packages and tools are used for development, testing an
 | [`wheel`](https://pypi.python.org/pypi/wheel)                                                                  | all               | packaging
 | [`twine`](https://pypi.python.org/pypi/twine)                                                                  | all               | packaging
 | [`toml`](https://pypi.python.org/pypi/toml)                                                                    | all               | packaging
-| [`Pillow`](https://python-pillow.org/)                                                                         | all               | packaging
+| [`pillow`](https://python-pillow.org/)                                                                         | all               | packaging
 | [`cx_Freeze` 6.11.1](https://pypi.org/project/cx_Freeze/)                                                      | Windows, MacOS    | packaging
 | `dpkg`                                                                                                         | Linux             | packaging
 | `alien`                                                                                                        | Linux             | packaging
@@ -78,7 +81,7 @@ These are the steps to set up the local repository ready to run PC-BASIC:
 
 2. Make pcbasic/data/USAGE.txt
 
-        python3.7 -m make docs
+        python3.7 -m make local
 
 3. Run pcbasic directly from the source directory
 
@@ -88,8 +91,8 @@ These are the steps to set up the local repository ready to run PC-BASIC:
 #### Deprecation warnings ####
 
 The following features are deprecated and **will be removed in the near future**:
-- Python 2.7 support
-- The [PyGame 1.9.3](www.pygame.org)-based interface
+- Support for end-of-life Python versions 2.7 and 3.6
+- The [PyGame](www.pygame.org)-based interface
 - The [curses](https://invisible-island.net/ncurses/)-based interface
 - The option `--utf8` (use `--text-encoding=utf8`)
 - The aliases `freedos`, `univga`, and `unifont` for the default font (use `--font=default`)

docs/__init__.py

@@ -0,0 +1,11 @@
+"""
+PC-BASIC - docs
+Documentation builder and source
+
+(c) 2013--2022 Rob Hagemans
+This file is released under the GNU GPL version 3 or later.
+"""
+
+from .usage import make_usage
+from .man import make_man
+from .htmldoc import make_htmldoc

docsrc/doc.py docs/htmldoc.pydocsrc/doc.py renamed to docs/htmldoc.py

@@ -1,5 +1,5 @@
 """
-PC-BASIC - docsrc.doc
+PC-BASIC - docs.htmldoc
 HTML documentation builder
 
 (c) 2013--2022 Rob Hagemans
@@ -9,7 +9,7 @@
 import os
 import json
 from datetime import datetime
-from io import StringIO, open
+from io import StringIO
 
 from lxml import etree
 import markdown
@@ -19,8 +19,10 @@
 
 
 BASEPATH = os.path.dirname(os.path.realpath(__file__))
+SOURCE_PATH = os.path.join(BASEPATH, 'source')
 
-with open(os.path.join(BASEPATH, 'description.json'), encoding='utf-8') as desc_json:
+
+with open(os.path.join(SOURCE_PATH, 'description.json'), encoding='utf-8') as desc_json:
     DESCR_STRS = json.load(desc_json)
 
 
@@ -86,7 +88,7 @@ def _embed_style(html_file):
     doc = etree.parse(html_file, parser)
     for node in doc.xpath('//link[@rel="stylesheet"]'):
         href = node.get('href')
-        css = os.path.join(BASEPATH, href)
+        css = os.path.join(SOURCE_PATH, href)
         node.tag = 'style'
         node.text = '\n' + read_file(css) + '\n    '
         node.attrib.clear()
@@ -126,21 +128,16 @@ def _embed_options(html_file):
     with open(html_file, 'w', encoding='utf-8') as htmlf:
         htmlf.write(etree.tostring(doc, method='html').decode('utf-8'))
 
-def makedoc(header=None, output=None, embedded_style=True):
+def make_htmldoc(output_path, output_filename, *, header=None, embedded_style=True):
     """Build HTML documentation from sources."""
-    header = header or BASEPATH + '/header.html'
-    output = output or BASEPATH + '/../doc/PC-BASIC_documentation.html'
-    try:
-        os.mkdir(BASEPATH + '/../doc')
-    except OSError:
-        # already there, ignore
-        pass
+    header = header or SOURCE_PATH + '/header.html'
+    output = os.path.join(output_path, output_filename)
     basic_license_stream = StringIO()
     doc_license_stream = StringIO()
     readme_stream = StringIO()
     ack_stream = StringIO()
     _md_to_html(BASEPATH + '/../LICENSE.md', basic_license_stream)
-    _md_to_html(BASEPATH + '/LICENSE.md', doc_license_stream)
+    _md_to_html(SOURCE_PATH + '/LICENSE.md', doc_license_stream)
     _md_to_html(BASEPATH + '/../README.md', readme_stream, baselevel=0)
     _md_to_html(BASEPATH + '/../THANKS.md', ack_stream, 'acks_')
 
@@ -156,21 +153,21 @@ def makedoc(header=None, output=None, embedded_style=True):
     major_version = '.'.join(VERSION.split('.')[:2])
     settings_html = (
         '<article>\n'
-        + read_file(BASEPATH + '/settings.html').replace('0.0', major_version)
-        + '<hr />\n' + read_file(BASEPATH + '/options.html')
-        + read_file(BASEPATH + '/examples.html') + '</article>\n'
+        + read_file(SOURCE_PATH + '/settings.html').replace('0.0', major_version)
+        + '<hr />\n' + read_file(SOURCE_PATH + '/options.html')
+        + read_file(SOURCE_PATH + '/examples.html') + '</article>\n'
     )
     predoc = StringIO()
     predoc.write(quickstart_html)
-    predoc.write(read_file(BASEPATH + '/documentation.html'))
+    predoc.write(read_file(SOURCE_PATH + '/documentation.html'))
     predoc.write(settings_html)
-    predoc.write(read_file(BASEPATH + '/guide.html'))
-    predoc.write(read_file(BASEPATH + '/reference.html'))
-    predoc.write(read_file(BASEPATH + '/techref.html'))
-    predoc.write(read_file(BASEPATH + '/devguide.html'))
+    predoc.write(read_file(SOURCE_PATH + '/guide.html'))
+    predoc.write(read_file(SOURCE_PATH + '/reference.html'))
+    predoc.write(read_file(SOURCE_PATH + '/techref.html'))
+    predoc.write(read_file(SOURCE_PATH + '/devguide.html'))
     predoc.write('<article>\n' + ack_stream.getvalue()  + '</article>\n')
     predoc.write(licenses_html)
-    predoc.write(read_file(BASEPATH + '/footer.html'))
+    predoc.write(read_file(SOURCE_PATH + '/footer.html'))
     predoc.seek(0)
     now = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
     if embedded_style:

docsrc/man.py docs/man.pydocsrc/man.py renamed to docs/man.py

@@ -1,5 +1,5 @@
 """
-PC-BASIC - docsrc.man
+PC-BASIC - docs.man
 Manfile builder
 
 (c) 2013--2022 Rob Hagemans
@@ -10,34 +10,44 @@
 import re
 import json
 import gzip
-from io import StringIO, open
+from io import StringIO
 
 from lxml import etree
 
 
 # file locations
-BASEPATH = os.path.dirname(os.path.realpath(__file__))
-OPTIONS_HTML = os.path.join(BASEPATH, 'options.html')
-EXAMPLE_HTML = os.path.join(BASEPATH, 'examples.html')
-MORE_HTML = os.path.join(BASEPATH, 'moreman.html')
-DOC_PATH = os.path.join(BASEPATH, '..', 'doc')
-MAN_FILE = os.path.join(BASEPATH, '..', 'doc', 'pcbasic.1.gz')
+SOURCE_PATH = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'source')
+OPTIONS_HTML = os.path.join(SOURCE_PATH, 'options.html')
+EXAMPLE_HTML = os.path.join(SOURCE_PATH, 'examples.html')
+MORE_HTML = os.path.join(SOURCE_PATH, 'moreman.html')
 
-# setup metadata
-with open(os.path.join(BASEPATH, 'description.json'), encoding='utf-8') as desc_json:
+# long and short descriptions
+with open(os.path.join(SOURCE_PATH, 'description.json'), encoding='utf-8') as desc_json:
     DESC_STRS = json.load(desc_json)
 
 
-TROFF_ESCAPES = [
-    (u'\\', u'\\[rs]'), (u'-', u'\\-'), (u'|', u'\\||'),
-    (u'.', u'\\|.'), (u'"', u'\\[dq]'), (u"'", u"\\|'"),
-]
+def make_man(man_path, man_name):
+    """Convert HTML sources to manfile."""
+    title_html = '<h1>pcbasic</h1><p>%s</p>\n' % DESC_STRS['description']
+    desc_html = '<h3>Description</h2><p>%s</p>\n' % DESC_STRS['long_description']
+    options_html = open(OPTIONS_HTML).read()
+    examples_html = open(EXAMPLE_HTML).read()
+    more_html = open(MORE_HTML).read()
+    man_html = ''.join((title_html, desc_html, options_html, examples_html, more_html))
+    # output manfile
+    man_file = os.path.join(man_path, man_name)
+    with gzip.open(man_file, 'w') as man:
+        man.write(_html_to_man(man_html).encode('utf-8'))
 
 
 def _text_to_man(text):
     """Convert plain text to troff."""
     # escape special characters
-    for key, value in TROFF_ESCAPES:
+    troff_escapes = [
+        (u'\\', u'\\[rs]'), (u'-', u'\\-'), (u'|', u'\\||'),
+        (u'.', u'\\|.'), (u'"', u'\\[dq]'), (u"'", u"\\|'"),
+    ]
+    for key, value in troff_escapes:
         text = text.replace(key, value)
     # replace line feeds with spaces
     text = text.replace(u'\n', u' ')
@@ -79,21 +89,3 @@ def _html_to_man(html):
     manpage = '\'\\" t\n.pc\n.TH PCBASIC 1\n' + _convert_element(docroot)
     # replace two starting spaces (not sure where from)
     return re.sub('\t +', '\t', re.sub('\n +', '\n', manpage))
-
-
-def makeman():
-    """Convert HTML sources to manfile."""
-    title_html = '<h1>pcbasic</h1><p>%s</p>\n' % DESC_STRS['description']
-    desc_html = '<h3>Description</h2><p>%s</p>\n' % DESC_STRS['long_description']
-    options_html = open(OPTIONS_HTML).read()
-    examples_html = open(EXAMPLE_HTML).read()
-    more_html = open(MORE_HTML).read()
-    man_html = ''.join((title_html, desc_html, options_html, examples_html, more_html))
-    try:
-        os.mkdir(DOC_PATH)
-    except EnvironmentError:
-        # already there, ignore
-        pass
-    # output manfile
-    with gzip.open(MAN_FILE, 'w') as manfile:
-        manfile.write(_html_to_man(man_html).encode('utf-8'))