Documentation image source

[Joel Sherrill]

On Wed, Oct 7, 2020, 8:12 PM Chris Johns <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>> 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.

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.



> >
> > 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.

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

--joel

>
> Chris
>
> >
> >     Sorry to be a pain about this but I think it is better we sort this
> out before
> >     we all move on and forget how they are created.
> >
> >     Chris
> >     _______________________________________________
> >     devel mailing list
> >     devel at rtems.org <mailto:devel at rtems.org>
> >     http://lists.rtems.org/mailman/listinfo/devel
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201007/0bf0d863/attachment.html>