View Issue Details

IDProjectCategoryView StatusLast Update
0027140mantisbtdocumentationpublic2023-02-13 05:57
Reporterdvzrv Assigned To 
PrioritynormalSeverityminorReproducibilityhave not tried
Status confirmedResolutionopen 
Summary0027140: tool used for documentation generation (publican) is more or less dead
Description

Hi! I package mantisbt for Arch Linux.
I am currently considering building the package directly from the auto-generated source tarball on github (as e.g. for 2.24.2 the generated tarball is not yet available on sourceforge).

I realized that I need publican to generate the administrator/developer documentation: https://github.com/mantisbt/mantisbt/tree/master/docbook

Looking at upstream, publican seems rather dead though: https://sourceware.org/publican/en-US/index.html and https://fedoraproject.org/wiki/Infrastructure/Fedorahosted-retirement
I can't package publican (due to missing sources) and therefore can not build mantisbt from source.

Looking at Fedora's own spec file for the publican package (https://src.fedoraproject.org/rpms/publican/blob/master/f/publican.spec) I can download a tarball for release 4.3.2 ("https://fedorahosted.org/released/publican/Publican-v4.3.2.tar.gz") but the tarball is a broken archive... :-/

It would be great to switch to some alternative tool for docbook , that is more widespread and still maintained.

TagsNo tags attached.

Relationships

related to 0031993 closeddregad Using Docker to build Documentation 

Activities

atrol

atrol

2020-08-09 06:53

developer   ~0064248

the generated tarball is not yet available on sourceforge

Meanwhile It's available.
Due to various reasons there is some delay until it's uploaded to SF and some more delay until it's replicated to all SF servers.

I am currently considering building the package directly from the auto-generated source tarball

Keep in mind there is not only the missing documentation, but also the missing 3rd party components installed by composer.

dregad

dregad

2020-08-09 08:04

developer   ~0064250

@dvzrv
I'm aware of the obsolescence of Publican, but switching the to a new toolchain and/or format is no small undertaking, and as much as I would like to do it, the conversion effort is unfortunately too great at the moment for the time I am able to invest in MantisBT.

I also failed to find Publican binaries after fedorahosted.org was killed, and even reported the issue but never got any response.

As for not being able to download the release tarballs from SourceForge, as an alternative you can always get the nightly build following the release from our own server (https://mantisbt.org/builds.php).

The latest version of the documentation is also available online in different versions including downloadable for offline viewing.

dvzrv

dvzrv

2020-08-11 12:41

reporter   ~0064255

@atrol: Yes, the missing 3rdparty components should be no problem though, as we can use composer to install them in the packaging process.

@dregad: I understand. Do you currently use a Fedora system to generate the docs? Maybe there is an easy alternative solution to publican.
If I come across one, I'll post it here!

dregad

dregad

2021-03-08 10:04

developer   ~0065203

Do you currently use a Fedora system to generate the docs

No, I'm on Ubuntu.

dregad

dregad

2023-02-12 04:34

developer   ~0067381

@dvzrv FYI, I started using Docker to build documentation on my dev box, see 0031993. Maybe this would be useful for you.

dvzrv

dvzrv

2023-02-13 04:30

reporter   ~0067385

@dvzrv FYI, I started using Docker to build documentation on my dev box, see 0031993. Maybe this would be useful for you.

@dregad: Sorry, but that doesn't solve the problem. It only pushes resolving it further into the future. ;-)

From a distribution perspective this is also not feasible and no downstream distribution will use this, as it is not reproducible and does not work with how downstream Linux distributions build packages (in clean chroots, only using other - previously packaged - packages).
Using a foreign container sadly just means, that no downstream distribution will package mantisbt, unless there's a pre-assembled tarball and that bitrot is ongoing.

I highly recommend porting to something still supported and developed (e.g. sphinx or a static site generator).

dregad

dregad

2023-02-13 05:57

developer   ~0067386

that doesn't solve the problem. It only pushes resolving it further into the future. ;-)

I know... Delaying the problem was the point actually ;-)

porting to something still supported and developed

As a matter of fact this is a task that's been on my to-do list for quite a while. I actually started thinking about it around 2019, and even made some tests to convert our DocBook XML to AsciiDoc, but then there was COVID and other real-life priorities... As always, "too many things to do, to little time"

It will happen, eventually. I just can't tell you when.

Until then, as mentioned before you can always download the built documentation from https://mantisbt.org/documentation.php - it is generated nightly (if there's been changes to it) and available in different formats (pdf, epub, txt, html). It is also bundled with our official releases on SourceForge.

Sorry there's not much more I can do for now.