Re: [STUMP] Drop the generation of stumpwm.texi

[David Bjergaard]

"Diogo F. S. Ramos" <address@hidden> writes:

>> I don't think the reduction in complexity will result in a
>> gain in productivity.  If we decouple stumpwm.texi from the source,
>> we'll have to maintain the docstrings and the documentation.  As it
>> stands right now, adding a function to the manual is a fairly
>> straightforward procedure of flagging the right symbols and the
>> makefile creates the appropriate stumpwm.texi file.
>
> The complexity reduction is one of the benefits which I see in this.
> There is also the fact that by editing `stumpwm.tex.in', sometimes it is
> not clear how the manual will turn up because there is still the
> processing part.
The with this is that having them coupled does not increase the
complexity of the workflow:
1. edit stumpwm.texi.in (usually to explain pedagogy)
2. type "make"
3. Read the resulting manual
4. Rinse and repeat.

The new proposed work flow would be exactly the same, the only
difference being that lisp would never be involved in making the
stumpwm.texi file.
>
> But maybe most importantly, I think docstrings and the manual should be
> separate entities.  Which means that, by separating them, there should
> not be more work to manually move text from the docstrings to function
> definitions in the manual, but that some texts might be similar for the
> functions which are mentioned in the manual.
While I (and others on github) disagree with this, I would like to point
out that having the docstrings together provides a uniform documentation
experience.  When I read the source code, I have the same documentation
as it will be presented in the manual.  Furthermore the docstrings from
the functions are fed to the online help system. (cf C-t h snext RET).
This ensures that anywhere a user gets documentation, they get the
*same* documentation.  I think the increased complexity in managing the
manual is worth providing a uniform experience to users.

This is kind of a "if it ain't broke, don't fix it" situation.  I had to
make significant manual updates for the last release, and while it was
initially cumbersome conceptually, it didn't take me long to figure out
how I needed to structure my edits so that they would render correctly.

Maybe we can address your concerns another way.  Besides reducing
complexity (which I agree, this proposal does), was there a reason that
you felt the need to make these changes?

Cheers,

    Dave