Page MenuHomeFreeBSD

Dynamic image support
ClosedPublic

Authored by bofh on Oct 13 2022, 10:43 PM.
Tags
Referenced Files
Unknown Object (File)
Thu, Nov 14, 10:35 AM
Unknown Object (File)
Thu, Nov 14, 10:27 AM
Unknown Object (File)
Thu, Nov 14, 10:23 AM
Unknown Object (File)
Thu, Nov 14, 10:10 AM
Unknown Object (File)
Wed, Nov 13, 8:54 AM
Unknown Object (File)
Tue, Nov 12, 12:33 PM
Unknown Object (File)
Tue, Nov 12, 4:04 AM
Unknown Object (File)
Mon, Nov 11, 9:28 PM

Details

Summary

Currently we have two types of images in our doc repo. One is screenshots/logos which are easy to replace and the other is images of flowcharts/plots/diagrams which are living in the repo as binary files. These binary files are hard to reproduce as the committers who designed those had the original image and no longer maintaining those and the original source is lost in history. For those diagrams we should use dynamic image generation. Asciidoctor has a plugin named Asciidoctor Diagram which can generate images from plaintext. There are multiple supported backends. I have only used Gnuplot to generate the ports count graph in the dev-model and we can use others too. This will also require an additional package which is rubygem-asciidoctor-diagram and this needs to be added in the docproj before we commit this. We will also need gnuplot-lite to generate this specific graph. For other flowcharts/diagram we can chose from one of the possible backends mentioned in the link.
I have also removed the original image from static so that there is no confusion is arising from this testing.

For this specific case we will not need to manually replace the svg diagram and commit it but as mentioned by @pauamma we will just one line of data in the image section mentioning Year 2023 and the count. And the image will be auto generated.

Test Plan
pkg install rubygem-asciidoctor-diagram gnuplot-lite
make DOC_LANG="en" -j32 all

Check the URL for the test result:
http://fdp.bofh.network/books/dev-model/index.html#fig-ports

Diff Detail

Repository
R11 FreeBSD ports repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

bofh requested review of this revision.Oct 13 2022, 10:43 PM
bofh created this revision.
pauamma_gundo.com added inline comments.
documentation/content/en/books/dev-model/_index.adoc
1119 ↗(On Diff #111776)

Needs alt text for accessibility.

This revision now requires changes to proceed.Oct 15 2022, 8:30 AM

@pauamma I appreciate your concern on accessibility but please don't pollute all the discussions with accessibility. I have mentioned in the earlier Review that the table will be fixed with the info you have provided and with the alt text which will go into another review. This review is not about fixing the texts or the tables either.

Hi,

AsciiDoctor, as a good software project don't have everything documented and sometimes you need to dig into their code hehe.

To fix the accesiblity problem, we need to change from this:

[gnuplot, target=portsstatus, format=svg]

to this:

[gnuplot, target=portsstatus, alt="Number of ports over the year", format=svg]

Well, I put "Number of ports over the year" as an example, be free to add the text you want.
Apart from that, approved, good to use more functionality from AsciiDoctor.

One more advantage to use (dynamically create) svg is it will be easy to support 'dark mode'.

@bofh Are you still working on it ?

In D36982#859054, @zlei wrote:

One more advantage to use (dynamically create) svg is it will be easy to support 'dark mode'.

@bofh Are you still working on it ?

Yes. I am still working on this. I am just running short of some times with other works in the tree. But we need to do the following:

  1. Add gnuplot as dependency in the docproj port which I plan to complete during Christmas Break
  2. Find out an application which can draw basic diagrams like flow chart, class diagrams graphs from Asciidoc. As we have lots of images which are just flow charts or class diagrams or graphs and needs to be updated regularly it's much easier to have text rather than binary images. The git diffs are short and is also easier for anyone to update those images with few lines of Asciidocs.
This revision was not accepted when it landed; it landed in state Needs Revision.Dec 28 2023, 6:53 AM
This revision was automatically updated to reflect the committed changes.

Sorry for the wrong revision.