Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 658780 - Remove asciidoc dependencies in favor of asciidoctor across the board
Summary: Remove asciidoc dependencies in favor of asciidoctor across the board
Status: RESOLVED FIXED
Alias: None
Product: Gentoo Linux
Classification: Unclassified
Component: Current packages (show other bugs)
Hardware: All Linux
: Normal normal (vote)
Assignee: Python Gentoo Team
URL:
Whiteboard:
Keywords: InOverlay
Depends on: 658778
Blocks:
  Show dependency tree
 
Reported: 2018-06-23 04:14 UTC by Amel Hodzic
Modified: 2019-11-11 16:34 UTC (History)
6 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Amel Hodzic 2018-06-23 04:14:10 UTC
Remove asciidoc dependencies in favor of asciidoctor across the board.


Reproducible: Always

Actual Results:  
asciidoc supports only python2.  The EOL for python2.7 is approaching.  We should remove dependencies on asciidoc in favor of asciidoctor to avoid implicit dependencies on python2.7.


FWIW, I've started some of the work in the [ag-ops](https://gitlab.com/ILMostro/ag-ops/) overlay.
Comment 1 Amel Hodzic 2018-06-23 04:54:16 UTC
https://gitlab.com/ILMostro/ag-ops/tags/v0.1.4

That has the eclass patched, as well as the listed packages, which do not inherit xorg-2.eclass.

dev-util/ninja
dev-vcs/git
net-libs/zeromq
sys-auth/ykpers
sys-fs/btrfs-progs
sys-kernel/dracut
sys-kernel/genkernel-next
x11-misc/compton
Comment 2 Amel Hodzic 2018-06-23 13:29:23 UTC
https://github.com/gentoo/gentoo/pull/8940
Comment 3 George L. Emigh 2018-06-25 00:40:47 UTC
A python 3 port of asciidoc is available.
https://github.com/asciidoc3/asciidoc3

Seems it would be easier just to use it.
Comment 4 Amel Hodzic 2018-06-25 04:00:54 UTC
(In reply to George L. Emigh from comment #3)
> A python 3 port of asciidoc is available.
> https://github.com/asciidoc3/asciidoc3
> 
> Seems it would be easier just to use it.

I like it! I'm a bit confused about that option vs. https://github.com/asciidoc/asciidoc-py3, tbh.  Nevertheless, the asciidoc3.org website shows that it should be a viable option, based on their test results.

"AsciiDoc3 is 100% pure Python3. All of the onehundred and seventy testcases defined in the AsciiDoc v2 distribution pass without errors and a binary identical result. See the information given on this page for downloads and installation instructions."

I'm not sure if this option should be used instead of asciidoc or alongside it.  One notable change, which may or may not matter, is the use of the "asciidoc3" command, rather than "asciidoc".  It should be noted, as well, that asciidoc3 is not available in the portage tree.  I'm not sure how well-known and, consequently, well-tested it is.  Therefore, FWIW, I'm not sure which is easier to implement or a better option.
Comment 5 Amel Hodzic 2018-06-25 04:13:33 UTC
Given the fact that python is part of @system, it does make more sense, of course, to use asciidoc3 rather than asciidoctor.

Thanks, George.
Comment 6 George L. Emigh 2018-06-26 23:58:22 UTC
(In reply to ILMostro from comment #4)
> (In reply to George L. Emigh from comment #3)
> > A python 3 port of asciidoc is available.
> > https://github.com/asciidoc3/asciidoc3
> > 
> > Seems it would be easier just to use it.
> 
> I like it! I'm a bit confused about that option vs.
> https://github.com/asciidoc/asciidoc-py3, tbh.  Nevertheless, the
> asciidoc3.org website shows that it should be a viable option, based on
> their test results.
> 
> "AsciiDoc3 is 100% pure Python3. All of the onehundred and seventy testcases
> defined in the AsciiDoc v2 distribution pass without errors and a binary
> identical result. See the information given on this page for downloads and
> installation instructions."
> 
> I'm not sure if this option should be used instead of asciidoc or alongside
> it.  One notable change, which may or may not matter, is the use of the
> "asciidoc3" command, rather than "asciidoc".  It should be noted, as well,
> that asciidoc3 is not available in the portage tree.  I'm not sure how
> well-known and, consequently, well-tested it is.  Therefore, FWIW, I'm not
> sure which is easier to implement or a better option.

Seems asciidoc3 is ready to go, but the COPYRIGHT shows someone other than the original author did the port, but he does claim identical output as the original asciidoc, the asciidoc-py3 site seems to imply it's not quite ready for prime-time.
Comment 7 Virgil Dupras gentoo-dev 2018-08-06 15:53:57 UTC
I'm not sure we should be making that kind of migration effort. After all, it's upstream's choice to use a py2 package. The few cases I've looked at are non trivial and significant work is required to ensure proper output. This work should be done upstream.

There are many packages besides asciidoc that will keep py2 in the tree for a long time after EOL and I don't think there are significant security risks associated with generating documentation with an EOL python (not the same kind of risks as, for example, running a web app).

The best thing we can do I think is to open PRs upstream to convert their build script to asciidoctor.
Comment 8 Mike Gilbert gentoo-dev 2018-08-06 15:59:39 UTC
(In reply to Virgil Dupras from comment #7)
> The best thing we can do I think is to open PRs upstream to convert their
> build script to asciidoctor.

Please don't promote migrating to asciidoctor specifically. That trades a python dependency for a ruby dependency.

I much prefer the idea of making asciidoc support python 3.
Comment 9 Virgil Dupras gentoo-dev 2018-08-06 16:03:51 UTC
asciidoctor has the advantage of being supported and notorious. If we were to choose the asciidoc3 port, we'd have to audit the source code first because we go from a notorious project that is a dependency to many packages to an obscure port. That could be considered a breach of users' trust in asciidoc.
Comment 10 Mike Gilbert gentoo-dev 2018-08-06 16:22:44 UTC
(In reply to Virgil Dupras from comment #9)
> asciidoctor has the advantage of being supported and notorious.

And it has the big disadvantage of depending on ruby, for projects that otherwise have no use for ruby.
Comment 11 Virgil Dupras gentoo-dev 2018-08-06 16:39:18 UTC
Yes, the choice is difficult. That is why I think we shouldn't do anything on the Gentoo side. Many upstream will likely act differently (asciidoctor, asciidoc port, converting their doc to something else entirely) when faced with Python 2 EOL and any work we do now is likely to be useless.

Let's decide what to do with leftover projects when we start removing python_targets_python2_7 USE flags.
Comment 12 Amel Hodzic 2019-11-11 16:34:54 UTC
This issue seems to be resolved by Bug 661662

Therefore, I'm closing this; albeit, the title is a bit misleading, as the issue is removing python2 reliance/dependency of asciidoc.