Bug 88232 – app-doc/linuxdoc-tools: request for ebuild

• Product: Gentoo Linux
• Status: RESOLVED FIXED

[Description Josh Nichols (RETIRED) 2005-04-06 23:06:02 UTC]

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:

[Comment 1 Josh Nichols (RETIRED) 2005-04-06 23:21:49 UTC]

Created attachment 55538 [details]
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.

[Comment 2 Josh Nichols (RETIRED) 2005-04-06 23:22:29 UTC]

Created attachment 55539 [details, diff]
linuxdoc-tools-0.9.21-destdir.patch

Allows use of DESTDIR mostly.

[Comment 3 Josh Nichols (RETIRED) 2005-04-06 23:23:07 UTC]

Created attachment 55540 [details, diff]
linuxdoc-tools-0.9.13-letter.patch

from a Fedora spec

[Comment 4 Josh Nichols (RETIRED) 2005-04-06 23:23:37 UTC]

Created attachment 55541 [details, diff]
linuxdoc-tools-0.9.20-lib64.patch

from a Fedora spec

[Comment 5 Josh Nichols (RETIRED) 2005-04-06 23:24:15 UTC]

Created attachment 55542 [details, diff]
linuxdoc-tools-0.9.21-badif.patch

from a Fedora spec

[Comment 6 Josh Nichols (RETIRED) 2005-04-06 23:25:34 UTC]

Created attachment 55543 [details, diff]
linuxdoc-tools-0.9.20-strip.patch

from a Fedora spec

[Comment 7 Josh Nichols (RETIRED) 2005-05-10 19:23:41 UTC]

Created attachment 58634 [details]
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.

[Comment 8 Josh Nichols (RETIRED) 2005-05-10 19:26:51 UTC]

Created attachment 58636 [details, diff]
linuxdoc-tools-0.9.21-nomakedoc.patch

Disables the script I mentioned previously.

[Comment 9 Leonardo Boshell (RETIRED) 2005-07-12 19:49:37 UTC]

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).

[Comment 10 Aron Griffis (RETIRED) 2005-08-10 08:57:49 UTC]

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.

[Comment 11 Leonardo Boshell (RETIRED) 2005-08-10 09:50:17 UTC]

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?

[Comment 12 Aron Griffis (RETIRED) 2005-08-10 13:48:04 UTC]

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
...

[Comment 13 Leonardo Boshell (RETIRED) 2005-08-12 08:40:33 UTC]

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/

[Comment 14 Leonardo Boshell (RETIRED) 2005-08-13 03:41:11 UTC]

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.