docstrings in dired.el

docstrings in dired.el

[Roland Winkler]

I am trying to develop proced.el in analogy with dired.el. However,
I am always a bit annoyed by the fact that too many functions in
dired.el come with comments instead of docstrings. So I'll convert
these comments into docstrings (unless somebody is really unhappy
about that).

Roland

Re: docstrings in dired.el

[Michael Olson]

[-- Attachment #1: Type: text/plain, Size: 716 bytes --]

"Roland Winkler" <Roland.Winkler@physik.uni-erlangen.de> writes:

> I am trying to develop proced.el in analogy with dired.el. However,
> I am always a bit annoyed by the fact that too many functions in
> dired.el come with comments instead of docstrings. So I'll convert
> these comments into docstrings (unless somebody is really unhappy
> about that).

Sounds like a good idea to me.  One of these days I need to give CL.el
and friends some similar treatment.

-- 
|       Michael Olson  |  FSF Associate Member #652     |
| http://mwolson.org/  |  Hobbies: Lisp, HCoop          |
| Projects: Emacs, Muse, ERC, EMMS, ErBot, DVC, Planner |
`-------------------------------------------------------'

[-- Attachment #2: Type: application/pgp-signature, Size: 188 bytes --]

Re: docstrings in dired.el

[David Kastrup]

"Roland Winkler" <Roland.Winkler@physik.uni-erlangen.de> writes:

> I am trying to develop proced.el in analogy with dired.el. However,
> I am always a bit annoyed by the fact that too many functions in
> dired.el come with comments instead of docstrings. So I'll convert
> these comments into docstrings (unless somebody is really unhappy
> about that).

dired has an ancient history, from a time when DOC strings were still
occupying main memory.

M-x checkdoc RET

would probably help with the conversion.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: docstrings in dired.el

[Eli Zaretskii]

> Date: Fri, 23 May 2008 06:43:18 +0200
> From: "Roland Winkler" <Roland.Winkler@physik.uni-erlangen.de>
> 
> I am trying to develop proced.el in analogy with dired.el.

Thanks.  But while at that, could you also please change proced.el to
not rely on an external program such as `ps', at least not explicitly?
Every modern OS has APIs to access the same information as `ps' does;
providing primitives to do that from Lisp will make proced.el much
more portable than it is currently, and I think it will also be
faster.  The hodgepodge of OS-specific options we have in proced.el at
this time is really ugly, IMO.

TIA

Re: proced.el [was: docstrings in dired.el]

[Roland Winkler]

On Fri May 23 2008 Eli Zaretskii wrote:
> Thanks.  But while at that, could you also please change proced.el to
> not rely on an external program such as `ps', at least not explicitly?
> Every modern OS has APIs to access the same information as `ps' does;
> providing primitives to do that from Lisp will make proced.el much
> more portable than it is currently, and I think it will also be
> faster.  

I agree that some built-in functions would be much cleaner, because
the different implementations of ps already have given me some
headache. It seems that the options required by ps and the output it
generates are by far less standardized than those of ls used by
dired.

(I interpret your email such that you would consider it worth the
effort to implement this on the C level.)

My problem is just that this goes way beyond my skills.

If someone was willing and able to help me with that, I'd greatly
appreciate it. 

> The hodgepodge of OS-specific options we have in proced.el at this
> time is really ugly, IMO.

Definitely, I agree.

Roland

Re: proced.el [was: docstrings in dired.el]

[Eli Zaretskii]

> Date: Fri, 23 May 2008 12:11:11 +0200
> From: "Roland Winkler" <Roland.Winkler@physik.uni-erlangen.de>
> Cc: emacs-devel@gnu.org
> 
> (I interpret your email such that you would consider it worth the
> effort to implement this on the C level.)

Yes, that's what I meant.

> My problem is just that this goes way beyond my skills.

Well, maybe at least consider refactoring the current Lisp code so
that the code which relies on `ps' is limited to a few functions with
well-defined interfaces.  Then someone else could reimplement them in
a portable fashion.

Thanks.

Re: proced.el [was: docstrings in dired.el]

[Roland Winkler]

On Fri May 23 2008 Eli Zaretskii wrote:
> Well, maybe at least consider refactoring the current Lisp code so
> that the code which relies on `ps' is limited to a few functions with
> well-defined interfaces.  Then someone else could reimplement them in
> a portable fashion.

That's what I try anyway.

Re: proced.el [was: docstrings in dired.el]

[Eli Zaretskii]

> Date: Sat, 24 May 2008 02:51:34 +0200
> From: "Roland Winkler" <Roland.Winkler@physik.uni-erlangen.de>
> Cc: emacs-devel@gnu.org
> 
> On Fri May 23 2008 Eli Zaretskii wrote:
> > Well, maybe at least consider refactoring the current Lisp code so
> > that the code which relies on `ps' is limited to a few functions with
> > well-defined interfaces.  Then someone else could reimplement them in
> > a portable fashion.
> 
> That's what I try anyway.

That's good to hear.  I hope, as part of that, you are planning on
refactoring the usage of proced-command-alist and
proced-sorting-schemes-alist to hide the dependency on `ps's options
behind some more general API.

Re: proced.el [was: docstrings in dired.el]

[Roland Winkler]

> > > Well, maybe at least consider refactoring the current Lisp code so
> > > that the code which relies on `ps' is limited to a few functions with
> > > well-defined interfaces.  Then someone else could reimplement them in
> > > a portable fashion.
> > 
> > That's what I try anyway.
> 
> That's good to hear.  I hope, as part of that, you are planning on
> refactoring the usage of proced-command-alist and
> proced-sorting-schemes-alist to hide the dependency on `ps's options
> behind some more general API.

Well, on my GNU/linux system I have procps that supports sorting. As
far as I have been able to find out about ps for other system types,
they do not support any sorting. This is a bit nasty, because
sorting the cooked values in the output of ps can give different
results than sorting the raw data. Also, the START field gives me
some trouble. For systems like SunOS (then called STIME), it can
have values like "May 20" (note the space) and "17:55:11". Working
around such things for sorting and filtering will be ugly.
(I consider the START field as one of those proced should support
for sorting and filtering.)

> > I tend to think it is better to leave this unportable code in Lisp
> > than to move it to C, because I think the amount of unportable
> > code in C would be much much more.
> 
> Now I have a challenge in hand to prove that you are wrong.

If it gives a unified elisp interface, that would be nice...

> Obviously I can't decide what you work on, but let's not forget
> that we lived happily without proced at all (not even some simpler
> replacement), so I think there are more important things on which
> to work.

...Yet I agree with Stefan that a very fancy piece of code is
probably not worth the effort. 

I looked into the code of procps and found it very intransparent. On
the other hand, it seemed to me that the major complications in
procps concern the many different variants and dialects for the
options it can digest and the output it generates. Procps tries to
be a replacement for all the different versions and behaviors. Yet
the part of the code that collects the process information from the
system apparently does not contain, e.g., system-dependent
preprocessor flags. (Maybe I looked into the wrong part of the code,
but I didn't find them.) So maybe it is possible to have a not too
complicated emacs primitive that collects and returns the
information on system process (maybe with only one switch to
distinguish between user processes and all processes). Then the
cooking (sorting, filtering, etc.) could be done probably with less
effort in elisp.

Roland

Re: proced.el [was: docstrings in dired.el]

[Eli Zaretskii]

> Date: Sun, 25 May 2008 01:24:08 +0200
> From: Roland Winkler <roland.winkler@physik.uni-erlangen.de>
> Cc: emacs-devel@gnu.org
> 
> So maybe it is possible to have a not too complicated emacs
> primitive that collects and returns the information on system
> process (maybe with only one switch to distinguish between user
> processes and all processes). Then the cooking (sorting, filtering,
> etc.) could be done probably with less effort in elisp.

That is what I meant.  The idea is similar to ls-lisp.el: it calls
directory-files-and-attributes to collect the information about all
the files in a directory, then formats and sorts them in Lisp.

Re: proced.el [was: docstrings in dired.el]

[Richard M Stallman]

    Well, maybe at least consider refactoring the current Lisp code so
    that the code which relies on `ps' is limited to a few functions with
    well-defined interfaces.

I agree that would be good.

			      Then someone else could reimplement them in
    a portable fashion.

I tend to think it is better to leave this unportable code in Lisp
than to move it to C, because I think the amount of unportable
code in C would be much much more.

Re: proced.el [was: docstrings in dired.el]

[Eli Zaretskii]

> From: Richard M Stallman <rms@gnu.org>
> CC: Roland.Winkler@physik.uni-erlangen.de, emacs-devel@gnu.org
> Date: Sat, 24 May 2008 10:13:25 -0400
> 
> 			      Then someone else could reimplement them in
>     a portable fashion.
> 
> I tend to think it is better to leave this unportable code in Lisp
> than to move it to C, because I think the amount of unportable
> code in C would be much much more.

Now I have a challenge in hand to prove that you are wrong.

Re: proced.el

[Stefan Monnier]

>> Then someone else could reimplement them in
>> a portable fashion.
>> 
>> I tend to think it is better to leave this unportable code in Lisp
>> than to move it to C, because I think the amount of unportable
>> code in C would be much much more.

> Now I have a challenge in hand to prove that you are wrong.

Obviously I can't decide what you work on, but let's not forget that we
lived happily without proced at all (not even some simpler replacement),
so I think there are more important things on which to work.  How 'bout
fixing some of the bugs at http://emacsbugs.donarmstrong.com/emacs ?


        Stefan

Re: proced.el

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sat, 24 May 2008 14:57:01 -0400
> Cc: Roland.Winkler@physik.uni-erlangen.de, rms@gnu.org, emacs-devel@gnu.org
> 
> Obviously I can't decide what you work on, but let's not forget that we
> lived happily without proced at all (not even some simpler replacement),
> so I think there are more important things on which to work.  How 'bout
> fixing some of the bugs at http://emacsbugs.donarmstrong.com/emacs ?

You are confused: it's Roland who works on proced.el, not me.  Or are
you saying that everybody else can work on new development, but I
should work on fixing bugs?

Re: proced.el

[Stefan Monnier]

>> Obviously I can't decide what you work on, but let's not forget that we
>> lived happily without proced at all (not even some simpler replacement),
>> so I think there are more important things on which to work.  How 'bout
>> fixing some of the bugs at http://emacsbugs.donarmstrong.com/emacs ?

> You are confused: it's Roland who works on proced.el, not me.

I was referring to your "Now I have a challenge in hand to prove that
you are wrong", which seemed to imply that you intended to come up with
the C-level code to prove Richard wrong.

> Or are you saying that everybody else can work on new development, but
> I should work on fixing bugs?

;-)


        Stefan

Re: docstrings in dired.el

[Richard M Stallman]

    Every modern OS has APIs to access the same information as `ps' does;
    providing primitives to do that from Lisp will make proced.el much
    more portable than it is currently, and I think it will also be
    faster.

I agree this can be cleaner, but if you add clean primitives to get
all this information, it will be a lot of bloat in the C code.  And
since that code will be totally different for different systems, it
will increase rather than decrease the system-specific code.  It will
mean a big addition the Emacs Lisp manual, if we document it.  I think
that these interfaces will never be needed for anything else.

All in all it seems we are better off with what we have now.

A simple primitive that we could document as "get all data about all
processes now running" might perhaps avoid these drawbacks.

Re: docstrings in dired.el

[Eli Zaretskii]

> From: Richard M Stallman <rms@gnu.org>
> CC: Roland.Winkler@physik.uni-erlangen.de, emacs-devel@gnu.org
> Date: Fri, 23 May 2008 23:39:17 -0400
> 
> A simple primitive that we could document as "get all data about all
> processes now running" might perhaps avoid these drawbacks.

That's what I had in mind.