Bug 1839024 - fossil-doc is useless
Summary: fossil-doc is useless
Alias: None
Product: Fedora
Classification: Fedora
Component: fossil
Version: 32
Hardware: All
OS: All
Target Milestone: ---
Assignee: Dan Čermák
QA Contact: Fedora Extras Quality Assurance
Depends On:
TreeView+ depends on / blocked
Reported: 2020-05-22 10:55 UTC by Van de Bugger
Modified: 2021-02-12 01:47 UTC (History)
3 users (show)

Fixed In Version: fossil-2.12.1-2.fc32
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Last Closed: 2021-02-12 01:47:53 UTC
Type: Bug

Attachments (Terms of Use)

Description Van de Bugger 2020-05-22 10:55:23 UTC
Description of problem:

fossil-doc rpm is useless.

Version-Release number of selected component (if applicable):


How reproducible:


Steps to Reproduce:

1. dnf install fossil-doc

Actual results:

/usr/share/doc/fossil-doc/www is full of *.md and *.wiki files. These files are useful when they are committed into a fossil repository: 'fossil ui' starts web server which shows these pages to the user. 

*.md and *.wiki files in /usr/share/doc/fossil-doc/www are almost useless: they are plain text files, but they are not easily readable with text editor or text pager (e. g. 'less') because they include wiki markup as well as html tags. At the same time they are not readable with a web browser since they are not html files.

Expected results:

I would expect /usr/share/doc/fossil-doc contains either readable (with no much html and/or wiki markup) plain text files or html files.

Additional info:

I guess there is no simple way to convert *.md and *.wiki files to *.html files,  so I would suggest dropping fossil-doc package entirely.

Comment 1 Fedora Admin user for bugzilla script actions 2020-11-22 14:53:22 UTC
This package has changed maintainer in the Fedora.
Reassigning to the new maintainer of this component.

Comment 2 Fedora Admin user for bugzilla script actions 2020-11-24 14:53:53 UTC
This package has changed maintainer in the Fedora.
Reassigning to the new maintainer of this component.

Comment 3 Sheng Mao 2020-11-25 05:17:10 UTC
Actually there are two solutions for this:

1. use newly built fossil to create a new fossil repo and add `www` folders to fossil. This is easier and can be implemented in RPM

2. current fossil supports `wiki export -html` command, which generates HTML pages. But this method can only support wiki/technote objects. Project Documentation/embedded doc [0] is not supported. But I can implement that in fossil and try to commit to upstream (take longer).

[0]: https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki

Comment 4 Dan Čermák 2020-12-07 21:31:08 UTC
Sheng has kindly provided a fix that has been pushed to Rawhide. Could you take a look if this is sufficient for you?

Comment 5 Van de Bugger 2020-12-10 18:06:29 UTC
I took a look at fossil-doc-2.12.1-2.fc34.x86_64.rpm.

1. fossil-doc package does not require fossil package, while fossil executable is required to view the documentation. I think "Requires: fossil" or "Recommends: fossil" should be added to fossil-doc.

2. It is assumed that user should execute "fossil ui /usr/share/doc/fossil-doc/fossil-doc.fossil" in order to view the documentation. It is written in the package description, but who reads the package description when the package is already installed? I guess method to view fossil documentation is not obvious for fossil newbies. Consider adding a helper script /usr/bin/fossil-doc like this one

    exec /usr/bin/fossil ui "$@" /usr/share/doc/fossil-doc/fossil-doc.fossil

or adding a kind of README

    Documentation in repository format for fossil. Users can run `fossil ui`
    in /usr/share/doc/fossil-doc folder to view documents in browser.

to /usr/share/doc/fossil-doc directory.

3. Search does not work for me. Run 

    $ fossil ui --page doc/trunk/www/permutedindex.html /usr/share/doc/fossil-doc/fossil-doc.fossil

then enter something in the input field and press "Search Docs" button. I see "Search is disabled" warning in red color after that.

4. Is fossil checkout really required? I tried to remove .fslckout file and www directory from /usr/share/doc/fossil-doc, and /usr/bin/fossil ui /usr/share/doc/fossil-doc/fossil-doc.fossil still works.

Comment 6 Sheng Mao 2020-12-16 03:31:32 UTC
Hi Van de Bugger, thank you for the comments! To conclude your suggestion:

- add dependencies for fossil-doc
- turn on searching/indexing
- create a script to run fossil, then no checked-out files are needed.

I agree with all three of them and will prepare a pull-request for defolos to review.

Comment 7 Sheng Mao 2020-12-17 04:19:17 UTC
Hi Van de Bugger,

Please check this pull-request for the updates: https://src.fedoraproject.org/rpms/fossil/pull-request/3 and pre-built COPR packages can be found at https://copr.fedorainfracloud.org/coprs/ivzhh/fossil/build/1839472/

Comment 8 Van de Bugger 2020-12-22 04:55:37 UTC

I checked fossil-doc-2.13-2.fc33.x86_64.rpm found at https://copr.fedorainfracloud.org/coprs/ivzhh/fossil/build/1839472/. It looks good.

Comment 9 Sheng Mao 2020-12-22 04:57:56 UTC
Thank you Van de Bugger! I will contact Dan for final review.

Comment 10 Fedora Update System 2021-02-03 21:01:31 UTC
FEDORA-2021-77648a0793 has been submitted as an update to Fedora 32. https://bodhi.fedoraproject.org/updates/FEDORA-2021-77648a0793

Comment 11 Fedora Update System 2021-02-04 01:26:30 UTC
FEDORA-2021-77648a0793 has been pushed to the Fedora 32 testing repository.
Soon you'll be able to install the update with the following command:
`sudo dnf upgrade --enablerepo=updates-testing --advisory=FEDORA-2021-77648a0793`
You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2021-77648a0793

See also https://fedoraproject.org/wiki/QA:Updates_Testing for more information on how to test updates.

Comment 12 Fedora Update System 2021-02-12 01:47:53 UTC
FEDORA-2021-77648a0793 has been pushed to the Fedora 32 stable repository.
If problem still persists, please make note of it in this bug report.

Note You need to log in before you can comment on or make changes to this bug.