[xml/sgml-pkgs] Bug#1101840: “LinuxdocTools::process_file: Cannot find favourites.gpx. Aborting” -- also, docs are wrong

[Agustin Martin]

On Tue, Apr 01, 2025 at 05:40:47PM +0200, Manny wrote:
> Package: linuxdoc-tools
> Version: 0.9.82-1
> Severity: normal
> Tags: upstream
> X-Debbugs-Cc: debbug.linuxdoc-tools at sideload.33mail.com
> 
> A simple attempt to validate SGML conformance of a GPX file from OSMand fails:
> 
>   $ linuxdoc -B check favourites.gpx
>   Processing file favourites.gpx
>   LinuxdocTools::process_file: Cannot find favourites.gpx. Aborting ...

Hi,

File is expected to have .sgml extension, and is to be specified as
either "$file.sgml" or "$file". Man page does not clearly explains that
and error message is indeed misleading.

I got a supposed .gpx file ("GPS_Exchange_Format") from somewhere and
linked "GPS_Exchange_Format.sgml" to "GPS_Exchange_Format",

$ linuxdoc -B check GPS_Exchange_Format
Processing file GPS_Exchange_Format
 DTD check - Error: this linuxdoc-tools package supports Linuxdoc DTD only.

   If you wish to convert DocBook or other DTD files,
     then please install and use SGMLTools-Lite or Jade/OpenJade package.

 --- LinuxDoc-Tools aborting.

If the same happens to you, I am afraid linuxdoc-tools is not the program
you expect, but your remarks are valid anyway. Please let me know if the
same happens to your .gpx file after linking as favourites.sgml. By the
way, sgmltools is no longer available in Debian.

> I have to say as well that the man page is wrong. For example, this is
> documented as a mandatory parameter:
> 
>   --papersize=size
> 
> But this would make no sense. Paper size is irrelevant to SGML
> docs. There is also a default (A4). If there is a default then it
> cannot be a mandatory option. So the correct BNF is to enclose it in
> square brackets, like this: [--papersize=size].

While it is irrelevant for the html backend is not for other backends like
LaTeX. However it has a default (as well as --language and -charset), so is
indeed optional, as well as --style, --debug, --define and --include.

> The obsolete command sgmlcheck seems to be correctly documented since
> the syntax is so simple. So I tried:
> 
>   $ sgmlcheck favourites.gpx
>   Processing file favourites.gpx
>   LinuxdocTools::process_file: Cannot find favourites.gpx. Aborting ...

Nothing strange, it is another frontend to linuxdoc main perl module.

I will try to improve all this in upstream code.

Thanks for your useful contribution, although linuxdoc-tools may not be
what you want.

Regards,

-- 
Agustin