nut-ddl.py.in

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
#   Copyright (C) 2014 - Daniele Pezzini <hyouko@gmail.com>
#   Copyright (C) 2022 - 2023 - Jim Klimov <jimklimov+nut@gmail.com>
#
#   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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

import re
import os
import pathlib
import argparse

###

# NOTE: Detailed documentation is in nut-ddl repo README file

# Path to NUT's manpages directory, relative to the working directory
manDir = "nut/docs/man/"
# Path to manpage directory in website
webManDir = "../../docs/man/"

# Currently not configurable, but maybe in the future we can make use of
# the difference of the two renderer projects with different features...
WITH_ASCIIDOCTOR = False

# Also not configurable externally now, but toggles rendering markup
# below as we experiment with it:
DEV_COMMENT_BLOCKS_AS_LIST = False #True

# Should we warn or fail when we see unique entries like comments twice, etc.?
PEDANTIC_DECLARATIONS = os.getenv("NUT_DDL_PEDANTIC_DECLARATIONS", "False")
# Booleanize this:
PEDANTIC_DECLARATIONS = (PEDANTIC_DECLARATIONS in ["True", "true", "TRUE", "Yes", "yes", "YES", "1"])

# This is not fatal, some documents do have layman comments,
# notably "# :; upsc output" before the data dump (such pattern
# is ignored to reduce noise when reviewing content). This feature
# just allows to track down comments that could be structured
# but were overlooked previously. Note however that this may
# also see issues with mis-typed structured comments if their
# lines are excluded by initial regex filter, e.g. like this one:
#   DEVICE:URL:REPORT: http://some.site/ and more text
# where the filter requires a single token or it is a plain comment.
# The important thing here is that such entries would not be rendered!
PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS = os.getenv("NUT_DDL_PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS", "False")
PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS = (PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS in ["True", "true", "TRUE", "Yes", "yes", "YES", "1"])

###

# Old (no longer available in NUT) -> new (currently available) drivers map
nutDriversUpdateMap = {
    # "old": "new",
    "blazer": "blazer_ser",
    "cpsups": "powerpanel",
    "cyberpower": "powerpanel",
    "esupssmart": "blazer_ser",
    "fentonups": "blazer_ser",
    "hidups": "usbhid-ups",
    "ippon": "blazer_ser",
    "liebertgxt2": "liebert-esp2",
    "megatec": "blazer_ser",
    "megatec_usb": "blazer_usb",
    "mustek": "blazer_ser",
    "newhidups": "usbhid-ups",
    "newmge-shut": "mge-shut",
    "nitram": "powerpanel",
    "powermust": "blazer_ser",
    "sms": "blazer_ser",
}

# Actually reported (yet available in NUT) -> new suggested drivers map
nutDriversHintsMap = {
    # "reported": "suggested",
    "apcsmart-old": "apcsmart",
    "bestups": "nutdrv_qx",
    "blazer_ser": "nutdrv_qx",
    "blazer_usb": "nutdrv_qx",
}

###

# Global vars

ndsVersion = "-1"
ndsSL = -1
varCmdComments = {}
devComment = []
devCommentBlocks = []
devURLs_vendor = []
devURLs_report = []
devURLs = []
nutVars = {}
nutRWs = {}
nutCommands = {}
manPages = []
fromFileName = {}
commentsMap = {}
nonCommentsMap = {}

###

# Command line arguments

parser = argparse.ArgumentParser(description="Parse a NUT's .dev/.nds file to AsciiDoc")
parser.add_argument("infile", help="Input file to parse (either .dev or .nds)")
parser.add_argument("outfile", help="Output file where the resulting page should be stored")
parser.add_argument("-v", "--verbose", action="store_true", help="Be pedantic about what's going on")
args = parser.parse_args()
inputFile = args.infile
outputFile = args.outfile
verbose = args.verbose

###

# Comments parsing

def nds_version(raw):
    """
    Parse NDS file version.
    """

    # '# NDS:VERSION:<version>\n'

    global ndsVersion

    if ndsVersion != "-1":
        msg = "Redeclaration of NDS version"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove '# NDS:VERSION:'
    ndsVersion = raw[0][14:]


def nds_sl(raw):
    """
    Parse user-provided support-level for the device.
    """

    # '# DEVICE:SUPPORT-LEVEL:<support-level>\n'

    global ndsSL

    if ndsSL != -1:
        msg = "Redeclaration of NDS support-level"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove '# DEVICE:SUPPORT-LEVEL:'
    sl = int(raw[0][23:])

    if not 1 <= sl <= 10:
        msg = ("NDS support-level: '%d' out of range [1..10]" % sl)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    ndsSL = sl


def nds_dev_url_vendor(raw):
    """
    Parse the URL for more device information
    (manufacturer/vendor/brander site or product page).
    May be present more than once, one URL per line.
    """

    # '# DEVICE:URL:VENDOR: *...\n'

    # Remove leading 'start' of the line ('# DEVICE:URL:VENDOR: *')
    line = str(raw[0][20:]).strip()

    # Empty comment
    if not len(line):
        msg = "Empty device vendor URL"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Too eager a copy-paste from asciidoc?
    if line.startswith("link:"):
        line = line.replace("link:", "", 1)

    if not "://" in line:
        msg = ("Device vendor URL does not contain a schema, ignored: %s" % line)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    devURLs_vendor.append(line)


def nds_dev_url_report(raw):
    """
    Parse the URL for more device information (mailing list, blog, NUT issue...)
    where the report originated, driver was implemented, etc.
    May be present more than once, one URL per line.
    """

    # '# DEVICE:URL:REPORT: *...\n'

    # Remove leading 'start' of the line ('# DEVICE:URL:REPORT: *')
    line = str(raw[0][20:]).strip()

    # Empty comment
    if not len(line):
        msg = "Empty device report URL"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Too eager a copy-paste from asciidoc?
    if line.startswith("link:"):
        line = line.replace("link:", "", 1)

    if not "://" in line:
        msg = ("Device report URL does not contain a schema, ignored: %s" % line)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    devURLs_report.append(line)


def nds_dev_url(raw):
    """
    Parse the URL for more device information (vendor site, NUT issue...)
    if not converted or suited to the more specific VENDOR or REPORT types.
    May be present more than once, one URL per line.
    """

    # '# DEVICE:URL: *...\n'

    # Remove leading 'start' of the line ('# DEVICE:URL: *')
    line = str(raw[0][13:]).strip()

    # Empty comment
    if not len(line):
        msg = "Empty device URL"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Too eager a copy-paste from asciidoc?
    if line.startswith("link:"):
        line = line.replace("link:", "", 1)

    if not "://" in line:
        msg = ("Device URL does not contain a schema, ignored: %s" % line)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    devURLs.append(line)


def nds_dev_comment(raw):
    """
    Parse device comment. Note that only one per device may be defined.
    See also DEVICE:COMMENT-BLOCK<:type>?: <title> which may be repeated
    for tool output "screenshots".
    """

    # '# DEVICE:COMMENT[:]\n'
    # '# <comment>\n'
    # '# <comment>\n'
    #	...
    # '# DEVICE:EOC\n'

    if len(devComment):
        msg = "Redeclaration of device comment (only one un-typed block is allowed)"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove leading 'start' line ('# DEVICE:COMMENT[:]\n')
    raw = raw[1:]

    # Not a valid device comment, don't do anything with it
    if not len(raw) or (raw[-1] != "# DEVICE:EOC" and raw[-1] != "# DEVICE:EOC:"):
        msg = ("Invalid device comment: %s" % ("seems empty" if not len(raw) else "does not end with DEVICE:EOC (blank non-comment lines mid-block?)"))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove the 'close' line
    raw = raw[:-1]

    # Empty comment
    if not len(raw):
        msg = "Empty device comment"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove hash and leading space
    for line in raw:
        devComment.append(line[2:])


def nds_dev_comment_block(raw):
    """
    Parse device block-comment(s) with pre-formatted text (tool "screenshots").
    """

    # '# DEVICE:COMMENT-BLOCK:UPSCONF: *<single-token title may be UPS name if no section in text, otherwise pasted as a starting comment>\n'
    # '# DEVICE:COMMENT-BLOCK:LSUSB: *<title with lsusb cmdline>\n'
    # '# DEVICE:COMMENT-BLOCK:LOGS: *<optional title>\n'
    # '# DEVICE:COMMENT-BLOCK:FIXME:UPSCMD: *<single-token title is UPS name for example command, multi-token is pasted as a starting comment>\n'
    # '# DEVICE:COMMENT-BLOCK:FIXME:UPSRW: *<single-token title is UPS name for example command, multi-token is pasted as a starting comment>\n'
    # '# DEVICE:COMMENT-BLOCK: *<title of unstructured info>\n'
    # '# <content-to-become-pre-formatted>\n'
    # '# <content-to-become-pre-formatted>\n'
    #	...
    # '# DEVICE:EOC\n'

    # Preferably titled like "Configuration section" or "lsusb listing",
    # or specifying the content type, or both in some cases. The cut-off
    # point is the colon char (comment_type_title starts with either type
    # or possible space and title right away):
    comment_type_title = str(raw[0][23:])
    try:
        # Variants of the remaining "type +/- title" to consider:
        # " *<empty>"
        # " *Some title (unstructured)"
        # "TYPE: *<empty>"
        # "TYPE: *Some title"
        # For regex below, currently the "TYPE:" is all-caps letters and colon
        # (may be inside, e.g. "FIXME:SOMETHING"); not adding more match chars
        # until needed by a syntax extension.
        matcher = re.match(r'^([A-Z:]+:)? *(.*)$', comment_type_title)
        if matcher:
            comment_type = matcher.group(1)
            title = matcher.group(2)
            if title is None:
                # Be sure it is a string type
                title = ""
        else:
            # Report below and use it all as title if not in pedantic mode
            raise ValueError("regular expression did not match expected pattern")
    except ValueError as exc:
        msg = ("Could not parse tag '%s' => tail '%s' further into a type and title: %s" % (str(raw[0]), comment_type_title, str(exc)))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        comment_type = None
        title = comment_type_title
    title = title.strip()
    # NOTE: Title validation continued after general content sanity check and trim

    # Remove leading 'start' line ('# DEVICE:COMMENT-BLOCK<:TYPE>: *<title>\n')
    raw = raw[1:]

    # Not a valid device block comment, don't do anything with it
    if not len(raw) or (raw[-1] != "# DEVICE:EOC" and raw[-1] != "# DEVICE:EOC:"):
        msg = ("Invalid device block comment: %s" % ("seems empty" if not len(raw) else "does not end with DEVICE:EOC (blank non-comment lines mid-block?)"))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove the 'close' line
    raw = raw[:-1]

    # Empty comment block
    if not len(raw):
        msg = "Empty device block comment"
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Collect stripped and prepared contents here:
    blk = []
    upsname = None

    # Pre-populate contents (and default title sometimes), as
    # based on caller-specified type and/or title of the entry:
    if comment_type == "UPSCONF:":
        # single-token title is UPS name, multi-token is pasted as a starting comment
        bGotSection = False
        bTitleComment = True
        upsname = None
        if len(title):
            if not " " in title:
                # ...else: multi-token, use as comment anyway
                # Below, we strip possible markup (so far don't care about proper nesting)
                upsname = re.sub(r"(^[\"'`[]*|[\"'`[]*$)", '', title)
                if not len(upsname):
                    upsname = None

        for line in raw:
            line = line[2:].strip()
            # No dollar, trailing comment syntactically possible:
            matcher = re.match(r'^\[([^ ]+)\]', line)
            if matcher:
                bGotSection = True
                if upsname is not None and matcher.group(1) == upsname:
                    bTitleComment = False
                break

        if not bGotSection:
            if upsname is None:
                msg = "Driver configuraton example lacks a section name for the device"
                if verbose:
                    print (msg)
                if PEDANTIC_DECLARATIONS:
                    raise RuntimeWarning (msg)
                # else: ugh, whatever
                blk.append("[ups]")
            else:
                blk.append("[%s]" % upsname)
                bTitleComment = False

        if len(title) and bTitleComment:
            blk.append("# %s" % title)

        # if not len(title):
        title = "Driver configuration"
    elif comment_type == "LSUSB:":
        if len(title):
            # Title assumed to be e.g. `lsusb -vvv` or `lsusb -s 007:002` (bus:dev)
            # or `lsusb -d 1234:5678` (vid:pid) or even `lsusb | grep Liebert`
            blk.append(":; %s" % title)
            title = "`%s` listing"
        else:
            if "lsusb" in raw[0]:
                title = "`lsusb` listing"
            else:
                # Assume the content starts with desired command, if posted
                title = "`lsusb` or similar tool listing"
    elif comment_type == "LOGS:":
        if not len(title):
            title = "Logs of NUT service startup"
    elif comment_type == "FIXME:UPSCMD:":
        # single-token title is UPS name for example command, multi-token is pasted as a starting comment
        bTitleComment = True
        upsname = "ups"
        if len(title):
            if not " " in title:
                # ...else: multi-token, use as comment anyway
                # Below, we strip possible markup (so far don't care about proper nesting)
                upsname = re.sub(r"(^[\"'`[]*|[\"'`[]*$)", '', title)
                if len(upsname):
                    bTitleComment = False

            if bTitleComment:
                blk.append("# %s" % title)
        # else: TODO: extract upsname from example command and/or
        # > Instant commands supported on UPS [myupsname]:
        # line, if any.

        if not "@" in upsname:
            upsname = upsname + "@localhost"

        # if not len(title):
        title = "Commands per `upscmd -l %s` listing" % upsname
        if "TODO" not in raw[0] and "FIXME" not in raw[0] \
                and (len(raw) < 2 or ("TODO" not in raw[1] and "FIXME" not in raw[1])):
            blk.append("# TODO: Convert to CMD:... markup")
        if "upscmd -l" not in raw[0] \
                and (len(raw) < 2 or "upscmd -l" not in raw[1]):
            blk.append(":; upscmd -l %s" % upsname)
        # else: TODO: rewrite upsname in example command and/or
        # > Instant commands supported on UPS [myupsname]:
        # line, if any? Perhaps to address below in the loop.
    elif comment_type == "FIXME:UPSRW:":
        # single-token title is UPS name for example command, multi-token is pasted as a starting comment
        bTitleComment = True
        upsname = "ups"
        if len(title):
            if not " " in title:
                # ...else: multi-token, use as comment anyway
                # Below, we strip possible markup (so far don't care about proper nesting)
                upsname = re.sub(r"(^[\"'`[]*|[\"'`[]*$)", '', title)
                if len(upsname):
                    bTitleComment = False

            if bTitleComment:
                blk.append("# %s" % title)
        # else: TODO: extract upsname from example command, if any

        if not "@" in upsname:
            upsname = upsname + "@localhost"

        # if not len(title):
        title = "Variables per `upsrw %s` listing" % upsname
        if "TODO" not in raw[0] and "FIXME" not in raw[0] \
                and (len(raw) < 2 or ("TODO" not in raw[1] and "FIXME" not in raw[1])):
            blk.append("# TODO: Convert to RW:... and RO:... markup")
        if ("upsrw" not in raw[0] or "upsrw output" in raw[0]) \
                and (len(raw) < 2 or ("upsrw" not in raw[1] or "upsrw output" in raw[1])):
            blk.append(":; upsrw %s" % upsname)
        # else: TODO: rewrite upsname in example command, if any?
        # Perhaps to address below in the loop.
    elif comment_type is not None:
        msg = ("Invalid device block comment type: '%s'" % str(comment_type))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        comment_type = None

    if not len(title):
        title = "Data sample"
        msg = ("Invalid device block comment title, using default: '%s'" % title)
        if verbose:
            print (msg)
        # if PEDANTIC_DECLARATIONS:
        #    raise RuntimeWarning (msg)

    # Loop to populate the rest of ultimately published contents, finally:
    for line in raw:
        # Remove hash and one leading space
        line = line[2:]
        lineStrip = line.strip()
        if comment_type == "FIXME:UPSRW:" and re.match(r'^upsrw output:*$', lineStrip):
            continue
        elif comment_type == "FIXME:UPSCMD:" and re.match(r'^upscmd output:*$', lineStrip):
            continue
        blk.append(line)

    devCommentBlocks.append({'title': title, 'content': blk})

def nds_var_cmd_comments(raw):
    """
    Parse comments of variables/commands.
    """

    # '# var.name[.suffix[. ...]]/command.name[.suffix[. ...]]:COMMENT[:]\n'
    # '# <comment>\n'
    # '# <comment>\n'
    #	...
    # '# var.name[.suffix[. ...]]/command.name[.suffix[. ...]]:EOC\n'

    # Get var/command name
    itemName = re.sub(":COMMENT:?.*$", "", raw[0][2:])

    if varCmdComments.get(itemName):
        msg = ("Redeclaration of comment for '%s'" % itemName)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove leading 'start' line
    raw = raw[1:]

    # Not a valid comment, don't do anything with it
    if not len(raw) or (raw[-1] != "# %s:EOC" % itemName and raw[-1] != "# %s:EOC:" % itemName):
        msg = ("Invalid comment for '%s': %s" % (itemName, "seems empty" if not len(raw) else "does not end with DEVICE:EOC (blank non-comment lines mid-block?)"))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    # Remove the 'close' line
    raw = raw[:-1]

    # Empty comment
    if not len(raw):
        msg = ("Empty comment for '%s'" % itemName)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    varCmdComments[itemName] = []

    # Remove hash and leading space
    for line in raw:
        varCmdComments[itemName].append(line[2:])


# Comments 'Pattern => parsing function' map for .nds files
ndsCommentsMap = {
    # N[UT]D[evice]S[imulation] version
    #  '# NDS:VERSION:<value>\n'
    "^# NDS:VERSION:\S+$": nds_version,
    # Vars/commands - Start of comment:
    #  '# var.name[.suffix[. ...]]/command.name[.suffix[. ...]]:COMMENT[:]\n'
    "^# ([\w\-]+\.)+[\w\-]+:COMMENT:?$": nds_var_cmd_comments,
    # Device - Start of comment block
    #  '# DEVICE:COMMENT-BLOCK: *<title>\n'
    "^# DEVICE:COMMENT-BLOCK:UPSCONF: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:LSUSB: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:LOGS: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:FIXME:UPSCMD: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:FIXME:UPSRW: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK: *.*$": nds_dev_comment_block,
    # Device - Start of comment
    #  '# DEVICE:COMMENT[:]\n'
    "^# DEVICE:COMMENT:?$": nds_dev_comment,
    # Further information about the device (vendor/mfr, issue/blog/mailing list, unclassified)
    #  '# DEVICE:URL:VENDOR:<link>\n'
    "^# DEVICE:URL:VENDOR: *[^ ]+://[^ ]+$": nds_dev_url_vendor,
    #  '# DEVICE:URL:REPORT:<link>\n'
    "^# DEVICE:URL:REPORT: *[^ ]+://[^ ]+$": nds_dev_url_report,
    #  '# DEVICE:URL:<link>\n'
    "^# DEVICE:URL: *[^ ]+://[^ ]+$": nds_dev_url,
    # Support level
    #  '# DEVICE:SUPPORT-LEVEL:<value>\n'
    "^# DEVICE:SUPPORT-LEVEL:\d\d?$": nds_sl
}


# Comments 'Pattern => parsing function' map for .dev files
devCommentsMap = {
    # Vars/commands - Start of comment:
    #  '# var.name[.suffix[. ...]]/command.name[.suffix[. ...]]:COMMENT[:]\n'
    "^# ([\w\-]+\.)+[\w\-]+:COMMENT:?$": nds_var_cmd_comments,
    # Device - Start of comment block
    #  '# DEVICE:COMMENT-BLOCK: *<title>\n'
    "^# DEVICE:COMMENT-BLOCK:UPSCONF: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:LSUSB: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:LOGS: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:FIXME:UPSCMD: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK:FIXME:UPSRW: *.*$": nds_dev_comment_block,
    "^# DEVICE:COMMENT-BLOCK: *.*$": nds_dev_comment_block,
    # Device - Start of comment
    #  '# DEVICE:COMMENT[:]\n'
    "^# DEVICE:COMMENT:?$": nds_dev_comment,
    # Further information about the device (vendor/mfr, issue/blog/mailing list, unclassified)
    #  '# DEVICE:URL:VENDOR:<link>\n'
    "^# DEVICE:URL:VENDOR: *[^ ]+://[^ ]+$": nds_dev_url_vendor,
    #  '# DEVICE:URL:REPORT:<link>\n'
    "^# DEVICE:URL:REPORT: *[^ ]+://[^ ]+$": nds_dev_url_report,
    #  '# DEVICE:URL:<link>\n'
    "^# DEVICE:URL: *[^ ]+://[^ ]+$": nds_dev_url,
    # Support level
    #  '# DEVICE:SUPPORT-LEVEL:<value>\n'
    "^# DEVICE:SUPPORT-LEVEL:\d\d?$": nds_sl
}

###

# End Of Comments patterns
EOCPatterns = [
    # Vars/commands comments
    #  '# var.name[.suffix[. ...]]/command.name[.suffix[. ...]]:EOC\n'
    "^# ([\w\-]+\.)+[\w\-]+:EOC:?$",
    # Device comment
    #  '# DEVICE:EOC\n'
    "^# DEVICE:EOC:?$"
]

###

# Non-comments parsing

def nds_vars(raw):
    """
    Parse NUT's vars.
    """

    # 'var.name[.suffix[. ...]]: <value>\n'

    # Check for End Of Line comments
    eol = None
    if len(raw["eol"]):
        for EOLType in EOLComments:
            if re.match(EOLComments[EOLType]["pattern"], raw["eol"]):
                eol = {
                    "type": EOLType,
                    "comment": EOLComments[EOLType]["function"](raw["eol"])
                }
                raw["eol"] = ""
                break

    varName = re.sub(":.*$", "", raw["line"])

    if nutVars.get(varName):
        msg = ("Redeclaration of variable '%s'" % varName)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    nutVars[varName] = {}

    nutVars[varName]["value"] = raw["line"].replace("%s:" % varName, "", 1)[1:]

    if eol is not None:
        nutVars[varName][eol["type"]] = eol["comment"]


def nds_rw_vars(raw):
    """
    Parse NUT's RW vars.
    """

    # For .nds files:
    # 'RW:var.name[.suffix[. ...]]:<type>:<options>\n'
    # For .dev files:
    # '#RW:var.name[.suffix[. ...]]:<type>:<options>\n'
    # '#RW:var.name[.suffix[. ...]]:STRING[:<len>]\n'

    # Check for End Of Line comments
    eol = None
    if len(raw["eol"]):
        for EOLType in EOLComments:
            if re.match(EOLComments[EOLType]["pattern"], raw["eol"]):
                eol = {
                    "type": EOLType,
                    "comment": EOLComments[EOLType]["function"](raw["eol"])
                }
                raw["eol"] = ""
                break

    buf = raw["line"].split(":", 4)

    varName = buf[1]
    varType = buf[2]

    if not nutRWs.get(varName):
        nutRWs[varName] = {}
        nutRWs[varName]["type"] = varType
    elif not nutRWs[varName].get("type") or nutRWs[varName]["type"] != varType:
        msg = ("Redeclaration of RW variable '%s' with mismatching types (%s != %s)" % (varName, varType, nutRWs[varName]["type"]))
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    if varType == "STRING":
        # 'RW:var.name[.suffix[. ...]]:STRING:<len>\n'
        # '#RW:var.name[.suffix[. ...]]:STRING[:<len>]\n'
        if fromFileName["fileType"] == "dev":
            if len(buf) < 4:
                buf.append("0")
        elif len(buf) < 4:
            msg = ("Declaration of RW variable '%s' of type 'STRING' without a length" % varName)
            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
        if not buf[3].isdigit():
            msg = ("Declaration of RW variable '%s' of type 'STRING' with an invalid length (%s)" % (varName, buf[3]))
            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
            return
        length = int(buf[3])
        if nutRWs[varName].get("opts"):
            if length != nutRWs[varName]["opts"]:
                msg = ("Redeclaration of variable '%s' of type 'STRING' with different length (%d != %d)" % (varName, length, nutRWs[varName]["opts"]))
            else:
                msg = ("Redeclaration of variable '%s' of type 'STRING'" % varName)

            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            return
        nutRWs[varName]["opts"] = length
        if eol is not None:
            nutRWs[varName][eol["type"]] = eol["comment"]
    elif varType == "ENUM":
        # 'RW:var.name[.suffix[. ...]]:ENUM:"<enumerated value>"\n'
        if not re.match("^\".+\"$", buf[3]):
            msg = ("Declaration of RW variable '%s' of type 'ENUM' with an invalid format." % varName) + \
                  ("\texpected: 'RW:var.name[.suffix[. ...]]:ENUM:\"<enumerated value>\"'") + \
                  ("\tgot: '%s'" % raw["line"])

            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
            return
        if not nutRWs[varName].get("opts"):
            nutRWs[varName]["opts"] = []
        opts = { "enum": buf[3][1:-1] }
        if eol is not None:
            opts[eol["type"]] = eol["comment"]
        nutRWs[varName]["opts"].append(opts)
    elif varType == "RANGE":
        # 'RW:var.name[.suffix[. ...]]:RANGE:"<min>" "<max>"\n'
        if not re.match("^\"\d+\" \"\d+\"$", buf[3]):
            msg = ("Declaration of RW variable '%s' of type 'RANGE' with an invalid range." % varName) + \
                  ("\texpected: 'RW:var.name[.suffix[. ...]]:RANGE:\"<min>\" \"<max>\"'") + \
                  ("\tgot: '%s'" % raw["line"])

            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
            return
        rwRange = buf[3].split("\"")
        if not len(rwRange[1]) or not rwRange[1].isdigit() or not len(rwRange[3]) or not rwRange[3].isdigit():
            msg = ("Declaration of RW variable '%s' of type 'RANGE' with a non-numerical range (%s..%s)" % (varName, rwRange[1], rwRange[3]))

            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
            return
        rangeMin = int(rwRange[1])
        rangeMax = int(rwRange[3])
        if not rangeMin < rangeMax:
            msg = ("Declaration of RW variable '%s' of type 'RANGE' with an invalid range (%d..%d)" % (varName, rangeMin, rangeMax))

            if verbose:
                print (msg)
            if PEDANTIC_DECLARATIONS:
                raise RuntimeWarning (msg)

            if not nutRWs[varName].get("opts"):
                del nutRWs[varName]
            return
        if not nutRWs[varName].get("opts"):
            nutRWs[varName]["opts"] = []
        opts = {
            "min": rangeMin,
            "max": rangeMax
        }
        if eol is not None:
            opts[eol["type"]] = eol["comment"]
        nutRWs[varName]["opts"].append(opts)
    else:
        if not nutRWs[varName].get("opts"):
            del nutRWs[varName]
        msg = ("Declaration of RW variable '%s' of unknown type '%s'." % (varName, varType))

        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)

        return


def nds_commands(raw):
    """
    Parse NUT's instant commands.
    """

    # For .nds files:
    # 'CMD:command.name[.suffix[. ...]]\n'
    # For .dev files:
    # '#CMD:command.name[.suffix[. ...]]\n'

    # Check for End Of Line comments
    eol = None
    if len(raw["eol"]):
        for EOLType in EOLComments:
            if re.match(EOLComments[EOLType]["pattern"], raw["eol"]):
                eol = {
                    "type": EOLType,
                    "comment": EOLComments[EOLType]["function"](raw["eol"])
                }
                raw["eol"] = ""
                break

    command = re.sub("^#?CMD:", "", raw["line"])

    if nutCommands.get(command):
        msg = ("Redeclaration of command '%s'" % command)
        if verbose:
            print (msg)
        if PEDANTIC_DECLARATIONS:
            raise RuntimeWarning (msg)
        return

    nutCommands[command] = {};

    if eol is not None:
        nutCommands[command][eol["type"]] = eol["comment"]


# Non-comments 'Pattern => parsing function' map for .nds files
ndsNonCommentsMap = {
    # Vars
    #  'var.name[.suffix[. ...]]: <value>\n'
    "^([\w\-]+\.)+[\w\-]+: .*$": nds_vars,
    # Empty vars
    #  'var.name[.suffix[. ...]]:\n'
    "^([\w\-]+\.)+[\w\-]+:$": nds_vars,
    # RW Vars
    #  'RW:var.name[.suffix[. ...]]:<type>:<options>\n'
    "^RW:([\w\-]+\.)+[\w\-]+:\w+:\S.*$": nds_rw_vars,
    # Commands
    #  'CMD:command.name[.suffix[. ...]]\n'
    "^CMD:(\w+\.)+\w+$": nds_commands
}


# Non-comments 'Pattern => parsing function' map for .dev files
devNonCommentsMap = {
    # Vars
    #  'var.name[.suffix[. ...]]: <value>\n'
    "^([\w\-]+\.)+[\w\-]+: .*$": nds_vars,
    # Empty vars
    #  'var.name[.suffix[. ...]]:\n'
    "^([\w\-]+\.)+[\w\-]+:$": nds_vars,
    # RW Vars
    #  '#RW:var.name[.suffix[. ...]]:<type>:<options>\n'
    #  '#RW:var.name[.suffix[. ...]]:STRING[:<len>]\n'
    "^#RW:([\w\-]+\.)+[\w\-]+:(STRING|\w+:\S.*)$": nds_rw_vars,
    # Commands
    #  '#CMD:command.name[.suffix[. ...]]\n'
    "^#CMD:(\w+\.)+\w+$": nds_commands
}

###

# End Of File patterns
EOFPatterns = [
    # Beginning of a sequence of [recorded] events
    "TIMER \d+"
]

###

# End Of Line parsing

def nds_bad(raw):
    """
    Parse bad vars/commands comments/flags.
    """

    #  '#BAD[: <comment>]\n'

    return re.sub("^[ \t]*#BAD:?\s*", "", raw)


def nds_comment(raw):
    """
    Parse End Of Line vars/commands comments.
    """

    #  '#COMMENT[: <comment>]\n'

    return re.sub("^[ \t]*#COMMENT:?\s*", "", raw)


# End Of Line 'Pattern => parsing function' map
EOLComments = {
    # Bad vars/commands
    #  '#BAD[: <comment>]\n'
    "bad": {
        "pattern": "[ \t]*#BAD:?.*$",
        "function": nds_bad
    },
    "comment": {
        "pattern": "[ \t]*#COMMENT:?.*$",
        "function": nds_comment
    }
}

###

def haveDetailedComments():
    """
    Based on collected information, estimate if we have any
    detailed comments to show for the particular report
    """
    return (len(devComment) or len(devURLs_vendor) or len(devURLs_report) or len(devURLs) or len(devCommentBlocks))

def parseFile(inputFile):
    """
    Parse inputFile to split it in comments/non-comments:
    Return:
    - a list of non-comments lines
    - a bidimensional list of comments lines
    """

    try:
        file = open(inputFile, "r")
    except IOError:
        print ("Cannot open", inputFile)
        exit(1)

    # Whether the last processed line was a comment and we can expect the actually processed one belongs to that comment
    commentContinuation = False

    # Whether we have encountered a NUT's 'EOF' and therefore have to ignore all non-comment lines
    ignoreNonComments = False

    # Index of comments entities in comments list
    i = -1

    comments = []
    nonComments = []

    linenum = 0
    for line in file:
        linenum = linenum + 1

        # Whether to bail out
        bailout = False

        # End Of Line comment (defaults to an empty string for non-matching lines)
        eol = ""

        # Check for known non-comments
        for pattern in nonCommentsMap:
            # Check for End Of Line comments
            for EOLType in EOLComments.values():
                if re.match(re.sub("\$", "[ \t]*", pattern) + EOLType["pattern"], line):
                    tempLine = re.sub(EOLType["pattern"], "", line)
                    bailout = True
                    # Just in case this is not the leftmost comment..
                    for innerEOLType in EOLComments.values():
                        if innerEOLType is EOLType:
                            continue
                        if re.search(innerEOLType["pattern"], tempLine):
                            bailout = False
                            break
                    if not bailout:
                        continue
                    eol = re.search(EOLType["pattern"], line).group(0)
                    line = tempLine
                    break
            if bailout:
                break
            if re.match(pattern, line):
                bailout = True
                break
        if bailout:
            if not ignoreNonComments:
                nonComments.append({
                    "line": line[:-1],
                    "eol": eol
                })
            commentContinuation = False
            continue

        # Check whether this line should be considered as the End Of File (such as recorded events' 'TIMER') and therefore we have to ignore all non-comments lines from now on
        for pattern in EOFPatterns:
            if re.match(pattern, line):
                bailout = True
                break
        if bailout:
            if not ignoreNonComments:
                msg = ("NUT's 'EOF' found, ignoring remaining non-comment lines: linenum=%s line: %s" % (linenum, str(line)))
                if verbose:
                    print (msg)
                # if PEDANTIC_DECLARATIONS:
                #     raise RuntimeWarning (msg)
                ignoreNonComments = True
            commentContinuation = False
            continue

        # Ignore empty lines, comments without the required leading space after the hash ('#<text>') and lines with spaces preceeding a hash, e.g. '   # comment ...\n'
        # note: an empty/'non-valid comment'/'indented comment' line 'breaks' a comment while an empty commented line ('#') doesn't
        # note: special markup lines like "#RW:...", "#RO:..." and "#CMD:..." are handled above as "known non-comments"
        if re.match("^(\s*|\s+#.*|#[^ \n\r].*)$", line):
            if PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS and "#" in line:
                print ("[%s:%d]\tUNSTRUCTURED COMMENT: %s" % (inputFile, linenum, str(line).strip()))
            commentContinuation = False
            continue

        # Comments
        if re.match("^#", line):
            # New entity
            for pattern in commentsMap:
                if re.match(pattern, line):
                    bailout = True
                    break
            if bailout:
                i += 1
                comments.append([])
                comments[i].append(line[:-1])
                commentContinuation = True
                continue

            # Entity continuation
            if commentContinuation:
                comments[i].append(line[:-1])
                # End Of Comment
                for pattern in EOCPatterns:
                    if re.match(pattern, line):
                        commentContinuation = False
                        break
            else:
                if PEDANTIC_TRACK_UNSTRUCTURED_COMMENTS and not "upsc" in line:
                    print ("[%s:%d]\tUNSTRUCTURED COMMENT: %s" % (inputFile, linenum, str(line).strip()))

            continue

        # Something unexpected
        print ("[%s#%d] Unexpected line: '%s'" % (inputFile, linenum, str(line[:-1])))
        exit(1)

    return comments, nonComments

###

def buildPage():
    """
    Build raw AsciiDoc page from data get from the input file.
    """

    # old .dev/.seq
    if fromFileName["fileType"] == "dev":
        simProgName = "dummy-ups"
        rwProgName = "upsrw"
        cmdProgName = "upscmd"
    # .nds
    else:
        simProgName = "dummy-ups" # TODO
        rwProgName = "upsrw" # TODO
        cmdProgName = "upscmd" # TODO

    page = []

    # New NUT version in page
    if fromFileName["reportNumber"] == 1:
        page.append("\n\n== %s\n" % fromFileName["nutVersion"])
    else:
        if PEDANTIC_DECLARATIONS:
            # Check that preceding numbers exist. Reminder from our spec:
            # <report-number> is the progressive number of reports available
            # for a device limited to a version of NUT (also if the driver,
            # <driver-name>, is different from one report to another), i.e.
            # for each device:
            # * every report being the first one for a particular version
            #   of NUT must have a report number equal to 01.
            # * every report still in the same version number must increase
            #   the report number also if the driver is not the same as the
            #   other ones.
            num = fromFileName["reportNumber"]
            assert (num is not None and num > 0)

            # FIXME: Here we currently hardcode that report numbers have
            # two-digit lengths. If this ever gets to vary, extend here.
            repnumlen = 2

            # See also: getInfoFFN() parsing
            # [/path/to/]<manufacturer>__<model>__<driver_name>__<NUT_version>__<report_number>.{dev,nds}
            repGlob = re.sub(
                    r"^(.*__.*__).*(__.*__\d+)$",
                    r"\1*\2",
                    fromFileName["fileName"]
                ) + "." + fromFileName["fileType"]
            while num > 1:
                num = num - 1
                zNum = str(num).zfill(repnumlen)
                prevFileGlob = re.sub(
                    r"__0*%s(\....)$" % fromFileName["reportNumber"],
                    r"__%s\1" % zNum,
                    repGlob)
                prevFiles = list(pathlib.Path(
                        "." if fromFileName["filePath"] is None or not len(fromFileName["filePath"]) else fromFileName["filePath"]
                    ).glob(prevFileGlob))
                if prevFiles is None or len(prevFiles) != 1:
                    msg = "While processing file %s discovered that a single preceding report file numbered %s does not exist: %s: matched %s" % (
                            inputFile, zNum,
                            os.path.sep.join([fromFileName["filePath"], str(prevFileGlob)]),
                            str(prevFiles)
                        )
                    if verbose:
                        print (msg)
                    raise RuntimeWarning (msg)

    # Note: report numbering should be sequential per NUT release
    # and may cover several drivers in it that handle the device:
    page.append("\n=== Report #%d with driver %s%s\n" % (fromFileName["reportNumber"], fromFileName["driverName"],
        " (detailed comments available)" if haveDetailedComments() else ""
        ))

    buf = "This device is known to work with driver "
    if fromFileName["driverName"] in manPages:
        buf += "link:%s%s.html[%s]" % (webManDir, fromFileName["driverName"], fromFileName["driverName"])
    else:
        buf += "%s" % fromFileName["driverName"]
    if nutDriversUpdateMap.get(fromFileName["driverName"]):
        replacement = nutDriversUpdateMap[fromFileName["driverName"]]
        buf += ", now replaced by the "
        if replacement in manPages:
            buf += "link:%s%s.html[%s]" % (webManDir, replacement, replacement)
        else:
            buf += "%s" % replacement
        buf += " one"
    buf += "."
    page.append(buf)

    suggested = False
    if nutDriversHintsMap.get(fromFileName["driverName"]):
        suggested = nutDriversHintsMap[fromFileName["driverName"]]
    elif nutDriversUpdateMap.get(fromFileName["driverName"]) and nutDriversHintsMap.get(nutDriversUpdateMap[fromFileName["driverName"]]):
        suggested = nutDriversHintsMap[nutDriversUpdateMap[fromFileName["driverName"]]]
    if suggested:
        buf = "It may also work with driver "
        if suggested in manPages:
            buf += "link:%s%s.html[%s]." % (webManDir, suggested, suggested)
        else:
            buf += "%s." % suggested
        page.append(buf)

    page.append("")

    buf = "You can grab a "
    if simProgName in manPages:
        buf += "link:%s%s.html[%s]" % (webManDir, simProgName, simProgName)
    else:
        buf += "%s" % simProgName
    buf += " compliant +.%s+ file " % fromFileName["fileType"]
    # .nds files
    if fromFileName["fileType"] == "nds" and ndsVersion != "-1":
        buf += "(_v%s_) " % ndsVersion
    buf += "to simulate this device link:$$raw/%s.%s$$[clicking here]" % (fromFileName["fileName"].replace("%", "%25"), fromFileName["fileType"])
    # Old .dev/.seq files
    if fromFileName["fileType"] == "dev" and os.path.isfile(os.path.join(fromFileName["filePath"], fromFileName["fileName"] + ".seq")):
        buf += " and a +.seq+ file to simulate power events link:$$raw/%s.seq$$[clicking here]" % (fromFileName["fileName"].replace("%", "%25"))
    buf += ".\n"
    page.append(buf)

    if haveDetailedComments():
        page.append("Some more detailed comments are available <<anchor-about-%s-%s,after>> the \"Known supported...\" sections.\n" % (fromFileName["nutVersion"], fromFileName["reportNumber"]))

    # NUT vars
    page.append("\n==== Known supported variables\n")
    page.append("This device is known to support the following variables (values are just examples):\n")
    page.append("[horizontal]")

    for nutVar in sorted(nutVars):
        bad = nutVars[nutVar].get("bad")
        if bad is not None:
            page.append("[nut-ddl-bad-var]*%s*;;" % nutVar)
        else:
            page.append("*%s*;;" % nutVar)
        if len(nutVars[nutVar]["value"]):
            if bad is not None:
                page.append("[nut-ddl-bad-var-value]+pass:specialcharacters[%s ]+" % nutVars[nutVar]["value"].replace("]", "\]"))
            else:
                page.append("+pass:specialcharacters[%s ]+" % nutVars[nutVar]["value"].replace("]", "\]"))
        else:
            if bad is not None:
                page.append("[nut-ddl-bad-var-value]#{sp}# +")
            else:
                page.append(" +")

        # 'BAD' EOL comment
        if bad is not None and len(bad):
            page.append("+\n[role=\"nut-ddl-bad-var-text\"]\n--\n{sp} %s\n--" % bad)

        # RW vars
        if nutRWs.get(nutVar):
            page.append("+\n--")

            incipit = "This variable can be set through "
            if rwProgName in manPages:
                incipit += "link:%s%s.html[%s]" % (webManDir, rwProgName, rwProgName)
            else:
                incipit += "%s" % rwProgName

            if nutRWs[nutVar]["type"] == "STRING":
                bad = nutRWs[nutVar].get("bad")
                if bad is not None:
                    page.append("[role=\"nut-ddl-bad-string\"]");
                if nutRWs[nutVar]["opts"] != 0:
                    page.append("%s to a string value upto the length of `%d` characters." % (incipit, nutRWs[nutVar]["opts"]))
                else:
                    page.append("%s to a string value." % incipit)
                if bad is not None and len(bad):
                    page.append("\n[role=\"nut-ddl-bad-string-text\"]\n{sp} %s" % bad)
                elif nutRWs[nutVar].get("comment") and len(nutRWs[nutVar]["comment"]):
                    page.append("\n{sp} %s" % nutRWs[nutVar]["comment"])
            elif nutRWs[nutVar]["type"] == "RANGE":
                page.append("%s within the following ranges:\n" % incipit)
                for rwRange in nutRWs[nutVar]["opts"]:
                    bad = rwRange.get("bad")
                    if bad is not None:
                        page.append("- [nut-ddl-bad-range]#`%d`..`%d`#" % (rwRange["min"], rwRange["max"]))
                        if len(bad):
                            page.append("+\n[role=\"nut-ddl-bad-range-text\"]\n--\n{sp} %s\n--" % bad)
                    else:
                        page.append("- `%d`..`%d`" % (rwRange["min"], rwRange["max"]))
                    comment = rwRange.get("comment")
                    if comment is not None and len(comment):
                        page.append("+\n--\n{sp} %s\n--" % comment)
            elif nutRWs[nutVar]["type"] == "ENUM":
                page.append("%s to one of the following values:\n" % incipit)
                for enum in nutRWs[nutVar]["opts"]:
                    bad = enum.get("bad")
                    if bad is not None:
                        page.append("- [nut-ddl-bad-enum]+pass:specialcharacters[%s ]+" % enum["enum"].replace("]", "\]"))
                        if len(bad):
                            page.append("+\n[role=\"nut-ddl-bad-enum-text\"]\n--\n{sp} %s\n--" % bad)
                    else:
                        page.append("- +pass:specialcharacters[%s ]+" % enum["enum"].replace("]", "\]"))
                    comment = enum.get("comment")
                    if comment is not None and len(comment):
                        page.append("+\n--\n{sp} %s\n--" % comment)

            page.append("--")

        # End Of Line var comment
        comment = nutVars[nutVar].get("comment")
        if comment is not None and len(comment):
            page.append("+\n--\n{sp} %s\n--" % comment)

        # Var comment
        if varCmdComments.get(nutVar):
            page.append("+\n--")
            for commentLine in varCmdComments[nutVar]:
                page.append(commentLine)
            page.append("--")

        page.append("")

    # NUT instant commands
    if len(nutCommands):
        page.append("\n==== Known supported commands\n")

        buf = "This device is known to support the following "
        if cmdProgName in manPages:
            buf += "link:%s%s.html[NUT's instant commands]:\n" % (webManDir, cmdProgName)
        else:
            buf += "NUT's instant commands:\n"
        page.append(buf)

        for nutCommand in sorted(nutCommands):
            bad = nutCommands[nutCommand].get("bad")
            if bad is not None:
                page.append("- [nut-ddl-bad-command]*%s*" % nutCommand)
            else:
                page.append("- *%s*" % nutCommand)
            # 'BAD' EOL comment
            if bad is not None and len(bad):
                page.append("+\n[role=\"nut-ddl-bad-command-text\"]\n--\n{sp} %s\n--" % bad)
            # End Of Line command comment
            comment = nutCommands[nutCommand].get("comment")
            if comment is not None and len(comment):
                page.append("+\n--\n{sp} %s\n--" % comment)
            # Command comment
            if varCmdComments.get(nutCommand):
                page.append("+\n--")
                for commentLine in varCmdComments[nutCommand]:
                    page.append(commentLine)
                page.append("--")

        page.append("")

    # Device comment/support-level
    if haveDetailedComments() or ndsSL != -1:
        page.append("\n[[anchor-about-%s-%s]]\n" % (fromFileName["nutVersion"], fromFileName["reportNumber"]))
        page.append("==== About this device\n")
        # Support level
        if ndsSL != -1:
            page.append("*Support level*: *%d* (out of 10)\n" % ndsSL)
        # Device comment
        if len(devComment):
            for commentLine in devComment:
                page.append(commentLine)
        # Device report URL(s)
        if len(devURLs_report):
            # Note: asciidoc list is separated by a blank line
            page.append("\nReported at:\n")
            for commentLine in devURLs_report:
                page.append("* %s\n" % commentLine)
            page.append("\n")
        # Device vendor URL(s)
        if len(devURLs_vendor):
            # Note: asciidoc list is separated by a blank line
            page.append("\nVendor/Manufacturer information:\n")
            for commentLine in devURLs_vendor:
                page.append("* %s\n" % commentLine)
            page.append("\n")
        # Device URL(s) (unclassified)
        if len(devURLs):
            # Note: asciidoc list is separated by a blank line
            page.append("\nSee also:\n")
            for commentLine in devURLs:
                page.append("* %s\n" % commentLine)
            page.append("\n")
        # Block-formatted information piece(s) from the report:
        if len(devCommentBlocks):
            page.append("\nFurther system data or configuration example%s:\n" % (
                "s" if (len(devCommentBlocks) > 1) else ""
                ))
            for report in devCommentBlocks:
                if DEV_COMMENT_BLOCKS_AS_LIST:
                    ### Style this as a list with bold text for titles?
                    page.append("* *%s*:\n+\n------" % report['title'])
                else:
                    ### ...or style this as blocks which include the title
                    ### attribute (can't make them a bulleted list though)?
                    # NOTE: [%%collapsible] is an asciidoctor feature, but not asciidoc:
                    # https://docs.asciidoctor.org/asciidoc/latest/blocks/collapsible/#ex-collapsible
                    page.append(".%s%s\n------" % (report['title'],
                        "\n[%%collapsible]" if WITH_ASCIIDOCTOR else ""
                        ))

                for line in report['content']:
                    page.append(line)
                page.append("------\n")
            page.append("\n")

    page.append("")

    return page

###

def getInfoFFN():
    """
    Get info from file name.
    """

    # [/path/to/]<manufacturer>__<model>__<driver_name>__<NUT_version>__<report_number>.{dev,nds}
    [ fromFileName["filePath"], fileNameExt ] = os.path.split(inputFile)

    [ fromFileName["fileName"], fileExt ] = os.path.splitext(fileNameExt)

    fromFileName["fileType"] = fileExt[1:]

    if fromFileName["fileType"] not in [ "dev", "nds" ]:
        print ("%s: unexpected type of file" % inputFile)
        print ("\texpected: .dev/.nds")
        exit(1)

    # <manufacturer>__<model>__<driver_name>__<NUT_version>__<report_number>
    infos = fromFileName["fileName"].split("__")

    if len(infos) < 5:
        print ("%s: unsuitable name; expected:" % inputFile)
        print ("\t<manufacturer>__<model>__<driver_name>__<NUT_version>__<report_number>.{dev,nds}")
        exit(1)

    # Info From File Name:
    fromFileName["manufacturer"] = infos[0].replace("_", " ")
    fromFileName["driverName"] = infos[2]
    fromFileName["nutVersion"] = infos[3]

    if not infos[4].isdigit() or int(infos[4]) < 1:
        print ("%s: unsuitable report number '%s'; expected 1+" % (inputFile, infos[4]))
        exit(1)

    fromFileName["reportNumber"] = int(infos[4])

    # Set maps for parsing input file
    global commentsMap, nonCommentsMap
    # .dev files
    if fromFileName["fileType"] == "dev":
        commentsMap = devCommentsMap
        nonCommentsMap = devNonCommentsMap
    # .nds files
    else:
        commentsMap = ndsCommentsMap
        nonCommentsMap = ndsNonCommentsMap

###

# Start!

# Check if file exists..
if not os.path.isfile(inputFile):
    print ("Input file '%s' doesn't exist" % inputFile)
    exit(1)

# ..and it's not empty
if not os.stat(inputFile).st_size:
    print ("Input file '%s' is empty" % inputFile)
    exit(1)

# Get info from file name
getInfoFFN()

# Parse given file
comments, nonComments = parseFile(inputFile)

# Parse comment lines
for comment in comments:
    for pattern in commentsMap:
        if re.match(pattern, comment[0]):
            commentsMap[pattern](comment)
            break

# Parse non-comment lines
for nonComment in nonComments:
    for pattern in nonCommentsMap:
        if re.match(pattern, nonComment["line"]):
            nonCommentsMap[pattern](nonComment)
            # The previous function should have cleared the 'eol' comment, if not, the comment was not expected
            if len(nonComment["eol"]) and verbose:
                print ("Unexpected EOL comment: '%s'" % nonComment["eol"])
                print ("\tin line: '%s'" % nonComment["line"])
            break

# Check if we have some vars
if not len(nutVars):
    print ("Input file '%s' doesn't appear to be a valid .dev/.nds file" % inputFile)
    exit(1)

# List of manpages
try:
    for name in os.listdir(manDir):
        if os.path.isfile(os.path.join(manDir, name)) and name.endswith(".html") and name != "index.html":
            manPages.append(name[:-5])
except OSError:
    print ("Unable to get manpage list from '%s'" % manDir)

# Build page
page = buildPage()

# Write page to outputFile
# Note: no "pedantic" checks for these reports
try:
    # Already existing page
    if os.path.isfile(outputFile):
        if verbose:
            print ("'%s' already exists; overwriting it" % outputFile)
    # New page
    else:
        if verbose:
            print ("Creating new file '%s'" % outputFile)
    file = open(outputFile, "w")
    file.write("\n".join(page))
    file.close()
    if verbose:
        print ("'%s' written" % outputFile)
except IOError:
    print ("Unable to write parsed file to '%s'" % outputFile)
    exit(1)