Page MenuHomeFreeBSD

textproc/docproj: Add required dependencies of the new documentation tree
ClosedPublic

Authored by driesm.michiels_gmail.com on Feb 12 2021, 1:44 PM.

Details

Summary

It would be good if someone could screen the current dependencies if they are still needed for the new documentation tree. I imagine that all docbook related ports can be removed as dependency and probably many more.

Diff Detail

Repository
R11 FreeBSD ports repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

driesm.michiels_gmail.com retitled this revision from Add required dependencies of the new documentation tree to textproc/docproj: Add required dependencies of the new documentation tree.Feb 12 2021, 1:45 PM
lwhsu added a subscriber: lwhsu.

I suggest we bump PORTVERSION to 3.0 and remove docbook related dependencies.

Yes, I think it's a good idea to remove the Docbook dependencies.

I went ahead and removed one dependency at a time and tried building the old English docs.
I removed each dependency from the port that caused a failure with the old doc tree.
So dependencies that are required to build the old doc tree are now gone.

Steal patch from PR 253518, keep the GIT option.

Authors: Yasuhiro Kimura, Dries Michiels :-)
New doctree builds fine with this port installed, yay!

PDF_DESC is already defined in bsd.options.desc.mk. So you need not redefine it in Makefile.

textproc/docproj/Makefile
1

This line should be left as it is. It is discouraged to use it in new ports, yes. At the same time it is not desired to remove existing created-by lines. We should probably document it in the handbook. I had been confused about it as well 2 years ago before I learnt about this unwritten convention.

Has all the docs tree been converted to the ascii thing?

I had a look the other day and it looked like most bits were still using docbook, so we probably need to keep the dependencies.

Readd Created by Line.
Remove PDF_DESC.

@mat yes, everything it's converted to AsciiDoc. We can remove docbook.

I'll happily give approval for this from docs if it helps this commited.
It's much easier to remember one port than a handful (or having to look them up in the FDP).

In D28609#642417, @mat wrote:

Has all the docs tree been converted to the ascii thing?

I had a look the other day and it looked like most bits were still using docbook, so we probably need to keep the dependencies.

+1 just add the new dependencies here, as we have the legacy documentation,

and please, add po4a>=0.63_1:textproc/po4a to the TRANSLATOR_RUN_DEPENDS as well.

In D28609#642417, @mat wrote:

Has all the docs tree been converted to the ascii thing?

I had a look the other day and it looked like most bits were still using docbook, so we probably need to keep the dependencies.

+1 just add the new dependencies here, as we have the legacy documentation,

and please, add po4a>=0.63_1:textproc/po4a to the TRANSLATOR_RUN_DEPENDS as well.

Like this: https://people.freebsd.org/~dbaio/docproj-hugo.patch

At least for now.

When the legacy is gone, we can remove the rest.
https://www-legacy.freebsd.org/
https://docs-legacy.freebsd.org/

adamw added inline comments.
textproc/docproj/Makefile
25

Usually, depending on a binary rather than the version is preferred.

hugo:www/gohugo
36–40

GIT_DESC already exists in Mk/bsd.options.desc.mk and can be safely removed.

In D28609#642417, @mat wrote:

Has all the docs tree been converted to the ascii thing?

I had a look the other day and it looked like most bits were still using docbook, so we probably need to keep the dependencies.

+1 just add the new dependencies here, as we have the legacy documentation,

I don't understand why the legacy docs are still there. They are not kept up to date as far as I can tell.
What about copying the current "textproc/docproj" to lets say "textproc/docproj-legacy" and keep the patch as is for the new one.
Not everyone wants to pull in the legacy stuff for development on the new documentation tree.
Anyway I'm only a contributor so that just my contributing opinion. I don't feel strong either way as my initial patch was exactly that one (just adding the new deps).

and please, add po4a>=0.63_1:textproc/po4a to the TRANSLATOR_RUN_DEPENDS as well.

Thats true, maybe we should keep igor in there too.

I don't understand why the legacy docs are still there. They are not kept up to date as far as I can tell.

They're there so we have an easier reference for "how things used to be" without having to rely on archive.org or checking out an old tree and running a local branch. They have their uses in cases like this.
Down the road, once the new documentation, website, and everything else is in order, I think redirects will be setup with HTTP 301 (which should ensure that search engines, spiders and such pick up on the changes, so that nobody ends up on old documentation).
It's a work-in-progress though, and it's a tough call when this cut-over is going to be, since it's still relatively far into the future.

I will note that PDF is mentioned as an optional part in the FDP quickstart, but I don't think it's going worth holding up the review over this.

I think this is good now, and I've got no problem with it as just a documentation project member, but textproc/docproj is owned by the doceng team so it'll be up to one of them to accept.

I'll happily commit once it's been accepted by them. :)

Looks good to me, with my doceng hat on (but ENOPORTSCOMMITTER).

This revision is now accepted and ready to land.Apr 23 2021, 9:24 AM
dbaio requested changes to this revision.Apr 23 2021, 11:42 AM
dbaio added inline comments.
textproc/docproj/Makefile
27

python:3.6+,run here.
Python is necessary just to to run some scripts (to create toc-files) in the build process.

53

po4a>=0.63_1:textproc/po4a here.
this doesn't work with older versions and I updated it recently.

This revision now requires changes to proceed.Apr 23 2021, 11:42 AM
  • Define python version and only for runtime.
  • Order asciidoctor rundep alphabetically like the others
  • Specify minimum version of po4a
driesm.michiels_gmail.com marked an inline comment as done.
  • Actually define runtime for python
  • PDF default off as suggested

Approved as ports.
But keep the GIT_DESC please, it seems there is not an entry for it on Mk/bsd.options.desc.mk.

This revision is now accepted and ready to land.Apr 24 2021, 3:12 AM

@dbaio Since it has been approved by a ports commiter (you), doceng (bcr), and a doc commiter (me), can I go ahead and commit this to the ports tree, or do you want to?

@dbaio Since it has been approved by a ports commiter (you), doceng (bcr), and a doc commiter (me), can I go ahead and commit this to the ports tree, or do you want to?

Sure, go for it, please.