[STUMP] Drop the generation of stumpwm.texi

[David Bjergaard]

Hi Diogo,

I really appreciate your idea to reduce code complexity, this is always
something that I strive for in my projects. In this case however, 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.

A clear benefit from this is that you don't need to be able to compile
stumpwm to make the info manual, which bit me when I tried to provide
archive of past manuals for the github.io page. This is a fairly minor
issue though, since going forward we'll have the manuals each time
there's a major release.

I think a more productive change to StumpWM (in terms of code
complexity) would be repackaging the useful bits of stumpwm into
external packages.

Cheers,

Dave

PS. I'm replying here because of the wider audience, and I would
appreciate it if the discussion of this topic continued on
stumpwm-devel.

To generate the info manual, StumpWM first processes `stumpwm.texi.in',
scrapping the lisp source code, producing `stumpwm.texi', so it later
can be compiled by `makeinfo'.
I think we can reduce the complexity of this process by removing the
scrapping phase and separate the manual from function docstrings, which
IMO have separate purposes.
I opened a pull request on github so we could have some concrete picture
if there is interest in discussing this.
_______________________________________________
Stumpwm-devel mailing list
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel

[Diogo F. S. Ramos]

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.

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.

[David Bjergaard]

Post by Diogo F. S. Ramos

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.

Post by Diogo F. S. Ramos
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

[Diogo F. S. Ramos]

Post by David Bjergaard
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?

Reducing the complexity was not my only concern, like I stated before,
but thank you for the care.

[David Bjergaard]

Post by Diogo F. S. Ramos

Post by David Bjergaard
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?

Reducing the complexity was not my only concern, like I stated before,
but thank you for the care.

Can you elaborate, I know that it may feel like I'm not listening, but I
feel like I'm missing a deeper point. As I understand this (please,
please correct me):

1. A lisp docstring and a manual entry are two different things.
2. Scraping source code to generate documentation is awkward/bad/ugly.
3. Its hard to edit the manual and know what the final version is going
to look like.

Therefore, it makes sense to decouple the manual from the docstrings and
maintain a pedagogical info document, as well as the doc strings for
lisp hackers who are working with the source code directly.

Is this a fair assessment?

Cheers,

Dave

[Diogo F. S. Ramos]

Post by David Bjergaard

Post by Diogo F. S. Ramos
Reducing the complexity was not my only concern, like I stated before,
but thank you for the care.

Can you elaborate, I know that it may feel like I'm not listening, but I
feel like I'm missing a deeper point.

Oh, I didn't feel like you were not listening. I think we just disagree
about it.

I say we drop this.

[David Bjergaard]

Post by Diogo F. S. Ramos

Post by David Bjergaard

Post by Diogo F. S. Ramos
Reducing the complexity was not my only concern, like I stated before,
but thank you for the care.

Can you elaborate, I know that it may feel like I'm not listening, but I
feel like I'm missing a deeper point.

Oh, I didn't feel like you were not listening. I think we just disagree
about it.
I say we drop this.

No problem! Please feel free to raise any other issues here, or let us
know about any other problems you encounter. I know you wrote a few
days ago about developing a module, I hope to see what it is sometime
soon.

Cheers,

Dave

[Diogo F. S. Ramos]

I know you wrote a few days ago about developing a module, I hope to
see what it is sometime soon.

Heh.

It is not a new module. And it is just a silly one.

[David Bjergaard]

Post by Diogo F. S. Ramos

I know you wrote a few days ago about developing a module, I hope to
see what it is sometime soon.

Heh.
It is not a new module. And it is just a silly one.

I'm still interested :) I really need to do something about some of the
modules that we're hosting anyway (swm-emacs for sure). A number of
them have horrible bitrot. If your working on anything I'm very
interested to know!

I know that I haven't been able to incorporate your last two proposed
changes. Please don't be discouraged! I try to keep the project as
close to its original goals as possible. This is made difficult when
people interpret the goals differently than others (myself included).
Thanks for your patience.

Cheers,

Dave

[Ivan Kanis]

Post by David Bjergaard

Post by Diogo F. S. Ramos

I know you wrote a few days ago about developing a module, I hope to
see what it is sometime soon.

Heh.
It is not a new module. And it is just a silly one.

I'm still interested :) I really need to do something about some of the
modules that we're hosting anyway (swm-emacs for sure).

Hi,

What's swm-emacs that you are speaking of?

Ivan

[David Bjergaard]

Post by Ivan Kanis
Hi,
What's swm-emacs that you are speaking of?
Ivan

https://github.com/stumpwm/stumpwm-contrib/tree/master/util/swm-emacs

There's also stumpmacs:
https://gitorious.org/dss-project/stumpmacs/source/1a2d69f20f0843fce5c5213a539824020786ad27:stumpmacs

And Deep Space Window Manager's latest solution (which appears to be
cleaner than stumpmacs):
https://gitorious.org/dss-project/dswm-modules/source/1bd4a4db476cc2028e18272fc3164371ba1deab7:emacs/NEED

I want to port DSWM's emacs module back to stumpwm, but the last time I
looked at the code I had philosophical differences, so I ended up
half-assing something for swm-emacs.

If your interested in any of those options, they're ripe for pull
requests :).

Cheers,

Dave

PS. I knew I recognized your name! I've read your blog posts off of
planet.emacsen.org

[Diogo F. S. Ramos]

Post by David Bjergaard
I'm still interested :) I really need to do something about some of the
modules that we're hosting anyway (swm-emacs for sure). A number of
them have horrible bitrot. If your working on anything I'm very
interested to know!

It is in the Wiki.

It is a very simple module to do some primitive control of pulseaudio.

[David Bjergaard]

Post by Diogo F. S. Ramos

Post by David Bjergaard
I'm still interested :) I really need to do something about some of the
modules that we're hosting anyway (swm-emacs for sure). A number of
them have horrible bitrot. If your working on anything I'm very
interested to know!

It is in the Wiki.
It is a very simple module to do some primitive control of pulseaudio.

Actually this would be very useful to me, I currently use a very hackish
way of controlling pulse audio's volume with these in my stumpwmrc:
(defcommand vol-up () ()
"Increase the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') + 0xf00)) ) &> /dev/null"))
(defcommand vol-down () ()
"Decrease the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') - 0xf00)) ) &> /dev/null"))

A more lispy solution would be really awesome!

Dave

[Diogo F. S. Ramos]

Post by David Bjergaard
Actually this would be very useful to me, I currently use a very hackish
(defcommand vol-up () ()
"Increase the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') + 0xf00)) ) &> /dev/null"))
(defcommand vol-down () ()
"Decrease the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') - 0xf00)) ) &> /dev/null"))

Nice.

Post by David Bjergaard
A more lispy solution would be really awesome!

It is "more lispy" just because it uses more lisp expressions. In the
end, it calls `pacmd' and parses its output, just like yours.

[David Bjergaard]

Post by Diogo F. S. Ramos

Post by David Bjergaard
Actually this would be very useful to me, I currently use a very hackish
(defcommand vol-up () ()
"Increase the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') + 0xf00)) ) &> /dev/null"))
(defcommand vol-down () ()
"Decrease the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') - 0xf00)) ) &> /dev/null"))

Nice.

Post by David Bjergaard
A more lispy solution would be really awesome!

It is "more lispy" just because it uses more lisp expressions. In the
end, it calls `pacmd' and parses its output, just like yours.

This is still an improvement over my kludge. I can't even really
mentally parse what my code does anymore... I just know that when I
press the vol-up key, the volume goes up :).

Dave

[Scott Jaderholm]

I've been using the pavol contrib for the last couple years and I
absolutely love it and recommend anyone using pulseaudio check it out.
I love how it works well in two different keybinding scenarios. One is
if you bind a single key to say volume up or volume down, like a
hardware volume key. The other is when you binding it say "C-t v" you
can repeat commands without having to type the prefix again, so you
can do "C-t v kkkkkkjjjjjjmm" to turn the volume up several steps,
turn it down several steps, then mute and unmute.

https://gitorious.org/pavol/pavol/

I think I did need "flat-volumes = no" in /etc/pulse/daemon.conf for
it to work, so if you have a problem check that.

Scott

Post by David Bjergaard

Post by Diogo F. S. Ramos

Post by David Bjergaard
Actually this would be very useful to me, I currently use a very hackish
(defcommand vol-up () ()
"Increase the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') + 0xf00)) ) &> /dev/null"))
(defcommand vol-down () ()
"Decrease the volume from the shell"
(run-shell-command
"pacmd set-sink-volume 0 $(printf '0x%x' $(( $(pacmd dump|grep set-sink-volume|cut -f3 -d' ') - 0xf00)) ) &> /dev/null"))

Nice.

Post by David Bjergaard
A more lispy solution would be really awesome!

It is "more lispy" just because it uses more lisp expressions. In the
end, it calls `pacmd' and parses its output, just like yours.

This is still an improvement over my kludge. I can't even really
mentally parse what my code does anymore... I just know that when I
press the vol-up key, the volume goes up :).
Dave
_______________________________________________
Stumpwm-devel mailing list
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel

[Scott Jaderholm]

Post by David Bjergaard

Post by Diogo F. S. Ramos
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
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.

I wanted to share two things that I think might help here.

First, in Emacs when editing a .texi file you can run M-x
makeinfo-buffer and it will show the rendered info page in *info*.
With stumpwm.texi.in this won't do the processing step, but it can be
made to work I believe by customizing the variable
makeinfo-run-command to run something that foo_INFOPTS command in
Makefile.

Second, I wrote this command to render the docstring at point as
texinfo and display it in *info*.

(require 'thingatpt)

(defun jsj-render-docstring-as-texinfo ()
"Render the docstring at point in an *info* buffer."
(interactive)
(save-excursion
(while (in-string-p)
(backward-char))
(let ((docstring (thing-at-point 'sexp))
(file (make-temp-file "texinfo")))
(with-temp-file file
(insert "@setfilename " file " \n"
"@node Top\n")
(insert docstring))
(find-file file)
(makeinfo-buffer))))

Cheers,
Scott

[David Bjergaard]

Post by Scott Jaderholm
(require 'thingatpt)
(defun jsj-render-docstring-as-texinfo ()
"Render the docstring at point in an *info* buffer."
(interactive)
(save-excursion
(while (in-string-p)
(backward-char))
(let ((docstring (thing-at-point 'sexp))
(file (make-temp-file "texinfo")))
(with-temp-file file
(insert docstring))
(find-file file)
(makeinfo-buffer))))
Cheers,
Scott

This would be useful in stumpwm.el, can you open an issue against
stumpwm-contrib to remind me to add this at some point?

Dave