Drop the generation of stumpwm.texi

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

Drop the generation of stumpwm.texi

Diogo F. S. Ramos-2
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
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

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


"Diogo F. S. Ramos" <[hidden email]> writes:

> 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
> [hidden email]
> https://lists.nongnu.org/mailman/listinfo/stumpwm-devel

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> 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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> writes:

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> writes:

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> writes:

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

Ivan Kanis
November, 17 at 21:18 David Bjergaard wrote:

> "Diogo F. S. Ramos" <[hidden email]> writes:
>
>>> 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

--
You need to install an RTFM interface..
    -- BOFH excuse #56

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

Diogo F. S. Ramos-2
In reply to this 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.

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> writes:

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
In reply to this 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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

Diogo F. S. Ramos-2
In reply to this post by David Bjergaard
> 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"))

Nice.

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard
"Diogo F. S. Ramos" <[hidden email]> writes:

>> 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"))
>
> Nice.
>
>> 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
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

scottjad
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


On Tue, Nov 18, 2014 at 10:24 AM, David Bjergaard <[hidden email]> wrote:

> "Diogo F. S. Ramos" <[hidden email]> writes:
>
>>> 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"))
>>
>> Nice.
>>
>>> 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
> [hidden email]
> https://lists.nongnu.org/mailman/listinfo/stumpwm-devel

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

scottjad
In reply to this post by David Bjergaard
On Mon, Nov 17, 2014 at 10:54 AM, David Bjergaard <[hidden email]> wrote:

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

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel
Reply | Threaded
Open this post in threaded view
|

Re: Drop the generation of stumpwm.texi

David Bjergaard


Scott Jaderholm <[hidden email]> writes:

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

_______________________________________________
Stumpwm-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/stumpwm-devel