RFC: Document the Wayland platform for a developer's eye

[Manolo]

Because being the only developer able to intervene in the Wayland-specific

FLTK code base is a dangerous situation, I propose to extend the FLTK Doxygen

documentation with a new chapter presenting in great detail the inner workings of FLTK's

Wayland platform with a developer's viewpoint.

An unfinished, but well advanced such document is attached here for an idea of

this proposal. That's a stand-alone .html file which lacks the integration of this

page in the rest of the FLTK documentation, but which is readable.

Alternatively, accessing branch wayland of my fltk fork (https://github.com/ManoloFLTK/fltk/) and building the FLTK documentation from it,  should produce the new Wayland development chapter, correctly integrated with the rest of the documentation.

Manolo

[Albrecht Schlosser]

On 1/20/23 18:08 Manolo wrote:

Because being the only developer able to intervene in the Wayland-specific

FLTK code base is a dangerous situation, I propose to extend the FLTK Doxygen

documentation with a new chapter presenting in great detail the inner workings of FLTK's

Wayland platform with a developer's viewpoint.

An unfinished, but well advanced such document is attached here for an idea of

this proposal. That's a stand-alone .html file which lacks the integration of this

page in the rest of the FLTK documentation, but which is readable.

Awesome, that's an excellent and very informative document.

+99 ;-) on including it somewhere in our docs

Alternatively, accessing branch wayland of my fltk fork (https://github.com/ManoloFLTK/fltk/) and building the FLTK documentation from it,  should produce the new Wayland development chapter, correctly integrated with the rest of the documentation.

That's great, I'll have a look at this tomorrow if I can find the time.


Question: Did you think about "hiding" this documentation in the "driver/developer" or any other conditional part?

My impression is that such a chapter would only be interesting for FLTK developers, hence my question.

There are (off the top of my head) three chapters I'd like to see in an appendix that is only generated if the driver option is enabled:

1. The current chapter "Developer Information" which deals with doxygen formatting. Most if not all of that chapter is only for FLTK developers. This chapter exists IIRC since 1.3.0 and was intended to be removed later. Maybe we should keep it but "hide" it in a developer appendix.

2. A chapter about Fl_Terminal intrinsics and Escape sequences which Greg is working on in his Fl_Terminal branch.

3. Your (Manolo's) new chapter about Wayland internals.


The CMake option for these special parts is OPTION_INCLUDE_DRIVER_DOCUMENTATION:BOOL=OFF. A quick search shows that this is controlled by a doxygen switch named `DriverDev` and this adds docs to the group `DriverDeveloper`:

src/fl_curve.cxx:31: \cond DriverDev
src/fl_curve.cxx:32: \addtogroup DriverDeveloper

This is only one of many examples, maybe this can be used, or we need another group/switch.

[Manolo]

Le dimanche 22 janvier 2023 à 01:27:24 UTC+1, Albrecht Schlosser a écrit :
Question: Did you think about "hiding" this documentation in the "driver/developer" or any other conditional part?

My impression is that such a chapter would only be interesting for FLTK developers, hence my question.

Reply :

As of today, the new chapter is a new, last item of "FLTK programming manual" (see attached).
My idea would be to leave it there initially, so fellow FLTK developers can access it easily and gain some

acquaintance with the Wayland backend, and to make it conditional to a build flag somewhat later,

for the reason you express.

[Manolo]

[Albrecht Schlosser]

On 1/22/23 12:07 Manolo wrote:
> As of today, the new chapter is a new, last item of "FLTK programming
> manual" (see attached).
> My idea would be to leave it there initially, so fellow FLTK
> developers can access it easily and gain some
> acquaintance with the Wayland backend, and to make it conditional to a
> build flag somewhat later,
> for the reason you express.

d'accord.

[Greg Ercolano]

    I think I'd brought this up before, developer only docs.
    Since the FLTK manual is already pushing 1000 pages, perhaps a separate
    "developer" doxygen document can be generated, so as not to distract app programmers.

[Albrecht Schlosser]

On 1/22/23 22:35 Greg Ercolano wrote:
>
>     I think I'd brought this up before, developer only docs.
>
>     Since the FLTK manual is already pushing 1000 pages, perhaps a
> separate
>     "developer" doxygen document can be generated, so as not to
> distract app programmers.
>

Yes, Matt started already fluid development docs (docs of the fluid
functions and classes), and Wayland would be another chapter. Moving the
doxygen related "developer docs" from the main docs to this chapter
would be another chapter.

I could imagine that 'README.bundled-libs.txt' would be another chapter.
I wrote this file so other devs could update the bundled image libs
easier (w/o guessing how to do this) and for my own reference.

Some docs that are now in the CMP, e.g. how to make a distribution
(incomplete), could also be added, and maybe more.

Looks like a good idea.

+1

[imacarthur]

On Sunday, 22 January 2023 at 21:35:38 Erco wrote:

    I think I'd brought this up before, developer only docs.

    Since the FLTK manual is already pushing 1000 pages, perhaps a separate
    "developer" doxygen document can be generated, so as not to distract app programmers.

I'm a bit slow getting to this (stuff happening here...) but have to say, when I saw Manolo's post about documenting the internals of the Wayland implementation, it very much brought to mind Greg's post about us having a (better) mechanism for developer docs (e.g. for the Text_Buffer implementation, Fl_Tree, etc...)

For whatever reason, Greg's proposal never seemed to gain any traction, but I think this shows that there may be a need for capturing developer docs, and probably distinct from the general user docs, since most folks will not be *that* invested in the internal details, I assume!

[Manolo]

Le dimanche 22 janvier 2023 à 22:35:38 UTC+1, Greg a écrit :

    I think I'd brought this up before, developer only docs.
    Since the FLTK manual is already pushing 1000 pages, perhaps a separate
    "developer" doxygen document can be generated, so as not to distract app programmers.

Agreed. I propose to create a new toplevel chapter "Development of the FLTK library"

with the same depth as "FLTK programming manual"  that would contain, to start with,

the new Wayland chapter and chapter "Developer info for bundled libs" that would

reformat the Doxygen way and replace file README.bundled-libs.txt.

All of that is in place in branch wayland of https://github.com/ManoloFLTK/fltk/

and can be tested with :

git clone https://github.com/ManoloFLTK/fltk fltk-M

cd fltk-M

git checkout wayland

mkdir build

cd build

cmake ..

make html

I also attach an image of the resulting tdocumentation table of contents

[Albrecht Schlosser]

On 1/24/23 08:13 Manolo wrote:

Le dimanche 22 janvier 2023 à 22:35:38 UTC+1, Greg a écrit :

    I think I'd brought this up before, developer only docs.
    Since the FLTK manual is already pushing 1000 pages, perhaps a separate
    "developer" doxygen document can be generated, so as not to distract app programmers.

Agreed. I propose to create a new toplevel chapter "Development of the FLTK library"

with the same depth as "FLTK programming manual"  that would contain, to start with,

the new Wayland chapter and chapter "Developer info for bundled libs" that would

reformat the Doxygen way and replace file README.bundled-libs.txt.

OK, that's a start, thanks. But that's not exactly what Greg proposed: a new document rather than a new chapter within the user document.

All of that is in place in branch wayland of https://github.com/ManoloFLTK/fltk/

and can be tested with ... [instructions removed]

I also attach an image of the resulting documentation table of contents

I would really like to have another document rather than a new chapter. To see why I made a simple example and added a '\todo' item to the new wayland docs. Here is the result:




The green rectangle shows the '\todo' item of the wayland developer documentation between user doc todo's. This may be a bad example (todo items are generally not useful for user docs), but it's just that: an example. It could happen.

The more pages we add to developer docs, the longer the user docs would be in total if we included the developer docs like this.

And yes, we might *exclude* the developer docs and their todo's and whatever from the user docs (by additional doxygen commands etc.), but I believe a clean start with a separate document would be a better choice for the future. In the future we could - and IMHO should - integrate the fluid docs as well. These are already prepared by Matt by documenting fluid's code and I just created the pdf version of fluid's developer docs to see how long these docs are: 684 pages, about half the size of the current FLTK user docs.

Manolo, please don't understand me wrong, what you did so far is a great start and I'm sure we could use everything in a new document. However, earlier or later we *will* need a separate document, and that's what Greg and Ian also suggested.

My vote is clear:

+1 to create a separate "FLTK Developer Documentation" document.

I volunteer to create the "infrastructure" (Doxyfile, CMake files [1], etc.) to do this for a beginning. Later new chapters and infos may be added by other devs.

[1] I also suggest that these developer docs can only be created with CMake to avoid duplicate work with configure/Makefiles.

[Manolo]

Le mardi 24 janvier 2023 à 15:24:36 UTC+1, Albrecht Schlosser a écrit :

My vote is clear:

+1 to create a separate "FLTK Developer Documentation" document.

I volunteer to create the "infrastructure" (Doxyfile, CMake files [1], etc.) to do this for a beginning. Later new chapters and infos may be added by other devs.

Agreed, as long as the new document is frequently updated and easily accessible to fellow FLTK developers.

[Albrecht Schlosser]

OK, I can do this, either on our GitLab mirror or on fltk.org, but I
believe our FLTK devs are able to create their own docs. ;-)


Please vote for a new, separate "Developer Documentation" document. This
new document will include:

- Manolo's additions:
  + new Wayland docs
  + bundled libs (replaces the README file)
- the current chapter "Developer Information" (likely with a new name, moved to the new docs)
- probably driver documentation which needs to be enabled explicitly in current (user) docs
- very likely "how to build a distribution" or something like that (replaces content in CMP)
- optionally (maybe later) fluid docs. Matt, what do you think?
- whatever else we may find useful...


My vote:

+1


I can imagine that Manolo merges his changes first (if others agree) and
I'll work based on that.

Manolo, how complete is your Wayland documentation, would you want to
work further on it before we merge?

[Manolo]

Le mardi 24 janvier 2023 à 16:33:36 UTC+1, Albrecht Schlosser a écrit :

Please vote for a new, separate "Developer Documentation" document. This
new document will include:

- Manolo's additions:
  + new Wayland docs
  + bundled libs (replaces the README file)
- the current chapter "Developer Information" (likely with a new name, moved to the new docs)
- probably driver documentation which needs to be enabled explicitly in current (user) docs

This will require to add many missing member function descriptions.

- very likely "how to build a distribution" or something like that (replaces content in CMP)
- optionally (maybe later) fluid docs. Matt, what do you think?
- whatever else we may find useful...

- Greg mentionned a detailed description of the new terminal widget he's preparing

 

My vote:

+1

Mine is +1 too.

 

I can imagine that Manolo merges his changes first (if others agree) and
I'll work based on that.

Yes, I can do that, if votes are positive.

 

Manolo, how complete is your Wayland documentation, would you want to
work further on it before we merge?

I believe it's decent now, although the GL-related part is still completely absent.

 

[Greg Ercolano]

On 1/24/23 07:33, Albrecht Schlosser wrote:

On 1/24/23 16:08 Manolo wrote:

Le mardi 24 janvier 2023 à 15:24:36 UTC+1, Albrecht Schlosser a écrit :

I volunteer to create the "infrastructure" (Doxyfile, CMake files [1], etc.) to do this for a beginning. Later new chapters and infos may be added by other devs.

Agreed, as long as the new document is frequently updated and easily accessible to fellow FLTK developers.

OK, I can do this, either on our GitLab mirror or on fltk.org, but I believe our FLTK devs are able to create their own docs. ;-)


Please vote for a new, separate "Developer Documentation" document. This new document will include:

- Manolo's additions:
  + new Wayland docs
  + bundled libs (replaces the README file)
- the current chapter "Developer Information" (likely with a new name, moved to the new docs)
- probably driver documentation which needs to be enabled explicitly in current (user) docs
- very likely "how to build a distribution" or something like that (replaces content in CMP)
- optionally (maybe later) fluid docs. Matt, what do you think?
- whatever else we may find useful...


My vote:

+1

    +1 for separate dev docs.

    And +1 for any docs that cover the "deep, dark rabbit holes",
    like Fl_Text_*, Fl_Help*, and I think me and Albrecht have gone down
    the focus/event/redraw hierarchy a few times..  more complicated
    than one would think.

    I certainly have a design document for Fl_Terminal ready to go.
    I'll try to move my src/README-Fl_Terminal.txt over to
    documentation/src/Fl_Terminal.dox instead.

    I should probably write similar docs for my other large-ish widgets
    Fl_Tree and Fl_Table.

    Other subjects that could be covered by devs that know them best,
    like our Unicode/utf8 handling, font measurement, etc. might be handy as well.

    I definitely like to see "top down" design philosophy for complex widgets;
    what thinking led to the design helps for quick maintenance/solutions, as
    devs unfamiliar with these widgets can at least anticipate design techniques
    if arrays are used in place of linked lists, etc. Sometimes just a few sentences
    of high level design can help a lot. There's many ways to design things, and
    one shouldn't have to unravel all the code just to figure out the top level design.
    Really helps get devs familiar with a widget quickly to speed up maintenance, I'd think.

[Manolo]

Le mardi 24 janvier 2023 à 16:33:36 UTC+1, Albrecht Schlosser a écrit :

Please vote for a new, separate "Developer Documentation" document.

We've had 3 +1 votes.

 

I can imagine that Manolo merges his changes first (if others agree) and
I'll work based on that.

That's now merged at commit f314ca7 .