Documentation image source

[Chris Johns]

On 8/10/20 2:23 pm, Joel Sherrill wrote:
> On Wed, Oct 7, 2020, 8:12 PM Chris Johns <chrisj at rtems.org
> <mailto:chrisj at rtems.org>> wrote:
>     On 8/10/20 12:04 pm, Joel Sherrill wrote:
>     > On Wed, Oct 7, 2020, 8:01 PM Chris Johns <chrisj at rtems.org
>     <mailto:chrisj at rtems.org>
>     > <mailto:chrisj at rtems.org <mailto:chrisj at rtems.org>>> wrote:
>     >
>     >     Hi,
>     >
>     >     In an update of my rtems-docs.git repo I noticed some new image source
>     formats:
>     >
>     >     $ find . -name \*.dot
>     >     ./images/eng/bld-bsp.dot
>     >     ./images/eng/bld-deps2.dot
>     >     ./images/eng/bld-bsp2.dot
>     >     ./images/eng/bld-deps.dot
>     >
>     >     Do we have a policy on what image source types can be used? Any
>     additional image
>     >     source needs to support FreeBSD and Linux.
>     >
>     >     Images can be difficult to get right so I understand there is a need for
>     >     flexibility and tolerance but I think we need to consider how we
>     manage the
>     >     process and quality so we maintained high quality documentation. For
>     example on
>     >     my desktop I cannot read the HTML `bld-deps.png` and clicking on it
>     loads a
>     >     small image which is clearer but small. The page is ...
>     >
>     >   
>      https://docs.rtems.org/branches/master/eng/build-system.html#build-specification-items
>     >
>     >     The PDF view looks OK.
>     >
>     >     I can see we have as image source the following extensions:
>     >
>     >      .puml
>     >      .ditaa
>     >      .svg
>     >      .dot
>     >      .odg
>     >
>     >     Some formats are old and imported so we live with those but maybe we need
>     >     tickets to have them move to something that is simpler to maintain.
>     >
>     >     I see generated .png and .pdf for some images which I am questioning
>     we need.
>     >     The user document images I have contributed are only .png files so I
>     am not sure
>     >     why a PDF is needed for some.
>     >
>     >     How are the .dot image sources converted to the required output
>     format(s)? I
>     >     cannot see any information on what to do, what packages I need to
>     install and
>     >     the options I need. For the puml and ditaa source I contributed I
>     added waf
>     >     support, tested on Linux and FreeBSD and update the top level doco.
>     >
>     >
>     > Graphviz.
> 
>     Thanks but I was hoping for something a little more specific, like a `pkg
>     install ...` command and a command line to run. I think it is important when
>     wanting to maintaining quality. :)
> 
> That is the name of the package. May vary with upper or lower case. CentOS RPM
> is graphviz.

I am sure it is something like that on FreeBSD. I have not looked.

> Are there any figures we do not appear to have source for? Or they aren't in an
> open format? I thought we had killed all those in our last Google Code In.

Good question, I think there are some I did a long time ago that might need to
be redone. The svg ones. I have not checked.

>     >
>     > If you can build Doxygen with graphics, you should have dot. We want dot
>     for sure.
>     >
> 
>     Sure, happy to be dot source integrated and managed.
> 
> I surprised one of my sons by using dot to show them the dependency graph for
> them to graduate on time. Coloured nodes based on semester offered and could
> visually identify longest sequence of courses and which had no prerequisites
> left for him.

That is such a nerd Dad solution! Well done, I love it :)

> PlantUML can draw more types of figures and they often look better but it can
> embed dot.

OK, I have not used dot so I do not know. The concern is not so much the tool
but the options used to make something work and be just right. We need to
capture what is used.

Chris