Bugzilla Bug 88232

From Debian's package description:
LinuxDoc is a kind of SGML DTD. It was created for the Linux HOWTOs, and had been used officially by the Linux Documentation Project (LDP). Now LDP has aggressively migrated into the DocBook world, but many documents are still available in LinuxDoc DTD sgml. So users may still need the tool for LinuxDoc, therefore LinuxDoc-Tools was created on the basis of sgml-tools_v1.

I'm working on making ebuilds for some programs that require linuxdoc-tools, so I'll be filing some dependent bugs soon.

Reproducible: Always
Steps to Reproduce:

Created an attachment (id=55538) [edit]
linuxdoc-tools-0.9.21.ebuild, largely inspired by a fedora spec

This is a mostly working ebuild. The only problem is some of the documentation.
The script called on line 130 in the main Makefile.in doesn't like being used
with DESTDIR, and assumes that the files of the package have been installed to
the system.

I have a patch for DESTDIR to work, except for what I just mentioned. There are
4 other patches that were used by the fedora spec that this ebuild was inspired
by.

Also, the license would need to be added to portage. It is located in
${S}/sgmls-1.1/LICENSE. My ebuild is assuming it is called SGMLUG.

Created an attachment (id=55539) [edit]
linuxdoc-tools-0.9.21-destdir.patch

Allows use of DESTDIR mostly.

Created an attachment (id=55540) [edit]
linuxdoc-tools-0.9.13-letter.patch

from a Fedora spec

Created an attachment (id=55541) [edit]
linuxdoc-tools-0.9.20-lib64.patch

from a Fedora spec

Created an attachment (id=55542) [edit]
linuxdoc-tools-0.9.21-badif.patch

from a Fedora spec

Created an attachment (id=55543) [edit]
linuxdoc-tools-0.9.20-strip.patch

from a Fedora spec

Created an attachment (id=58634) [edit]
inuxdoc-tools-0.9.21.ebuild

The script I previously had mentioned causes sandbox violations now, so I
patched the Makefile not to execute it. Not the best solution, I know, but I
need this package for some other packages I'm working on.

Created an attachment (id=58636) [edit]
linuxdoc-tools-0.9.21-nomakedoc.patch

Disables the script I mentioned previously.

The linuxdoc DTD and related tools are provided by sgmltools-lite. Any reason
why we should add this to our tree?

I don't know much about redhat's configuration tools (the bug being blocked by
this one), but I don't think we should rely on this package
(linuxdoc-tools-0.9.21, that is).

Leonardo, AFAICT you're mistaken regarding sgmltools-lite.  That package will
build from docbook sources, but doesn't handle linuxdoc sources.  In fact the
question is addressed here: http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc-6.html

I need linuxdoc-tools for generating the mutt documentation, so I might work on
this ebuild if nobody from text-markup is going to do it.

Aron,
I don't really know the history of those projects, but it seems like
sgmltools-lite is the replacement for linuxdoc and sgmltools (if those are in
fact two different packages).

I'm probably missing something, but I don't understand what you mean by "that
package will build from docbook sources, but doesn't handle linuxdoc sources".
sgmltools-lite provides the linuxdoc DTD as well as the various sgml2* programs.

What exactly is needed for the mutt documentation? If possible, could you point
to some particular documentation file so I can test it with the DTD from
sgmltools-lite?

Leonardo, you might be right, but I haven't gotten it to work.  Perhaps you
wouldn't mind investigating a little bit?  Here is an example of how it fails:

ebuild muttng-20050325.ebuild compile
...
sgml2html manual || true
/usr/bin/openjade:<OSFD>0:4:5:E: document type does not allow element "BOOK"
here; assuming missing "LINUXDOC" start-tag
/usr/bin/openjade:<OSFD>0:6:6:E: document type does not allow element "TITLE"
here; assuming missing "TITLEPAG" start-tag
/usr/bin/openjade:<OSFD>0:7:7:E: document type does not allow element "AUTHOR" here
...

Thanks for the reference. After testing with muttng's manual and studying this
a
little bit I see you were right in the first place :). It's a bit confusing, so
I'll try to summarize the situation for reference:

'sgml-tools' (aka. SGMLTools v1) was the original tool to process linuxdoc
documents. Then, after the linuxdoc format was deprecated in favour of docbook,
'sgmltools' (aka. SGMLTools v2) came to existance, which later became
SGMLTools-Lite[1].

The problem is sgmltools-lite actually doesn't process linuxdoc documents
directly. Adding to the confusion, and for some reason, it does provide the
linuxdoc DTD, and particularly strange is that our ebuild creates the
sgml2{txt,rtf,html} aliases, using sgmltools as backend (bug #1163). That seems
to be wrong, despite the advice found in [2]. Unfortunately, all my previous
testing with linuxdoc documents were with documents conforming the DocBook DTD
as well so I didn't detect this conflict.

So, linuxdoc-tools, a fork of SGMLTools v1, seems to be the toolset we should
have for linuxdoc documents (just as I said all along :)). I'm currently
working
in the ebuild, and on a new revision of sgmltools-lite so it doesn't have file
collisions with linuxdoc-tools. Once I test it with muttng's manual I think we
could commit it. I'll be happy to receive any other comments/suggestions..


[1] http://sourceforge.net/docman/display_doc.php?docid=12532&group_id=3928
[2] http://linux.bankhacker.com/en/software/SGMLTools/

OK, I've committed an ebuild for linuxdoc-tools. I've tested it with muttng,
and
it creates its manual correctly in HTML and plain text formats, so I'm marking
this buf resolved. Please open new bug reports for any additional
suggestions/problems.

Josh,
I appreciate your effort creating the initial ebuild and providing the patches.
However, most of them don't really apply in our case. Only the -letter and
-badif patches seem generic and potentially useful, but I'm being cautious for
now as I'd like to see some rationale about them before committing them. Maybe
someone more familiar with latex and friends could take a look at this.

Thanks everyone for the help.