Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus <rasmus@gmx.us>]

joaotavora@gmail.com (João Távora) writes:

>    [ Hi Rasmus, I took it from your thorough review of the code that you
>    accept to mentor this, in the framework discussed earlier. In the
>    future, perhaps change the subject line to "mentoring".

I hit F, write the message and then click C-c C-c.  Did you not include
the [mentoring] line to begin with?

> Rasmus <rasmus@gmx.us> writes:
>> Why is your mode preferable?
>
>     [ How convincing must the would-be-contributor be at this stage?
>     Won't opening with this question intimidate him/her? ]

Maybe.  This is the question my supervisor asks me every time I come up
with a new idea.  Indeed, it's a very unpleasant question, but one that
you need to consider no matter if you do code or try to write a thesis.

> I haven't done a thorough survey of other extensions, but I remember
> trying some that don't deal well with the margins, and none provide
> something like `darkroom-tentative-mode'.
>
>> Did you take care of the FSF paperwork?
>     [ I've contributed to Emacs earlier, so yes. Again should this
>       question be on top?]

Yeah, 'cause it takes time.  So the earlier the process the better.  If
you have not signed papers and do not intend to, I won't read your patch.


>>> I'm looking for pointers on how to clone the Emacs repository after the
>>> recent Git transition, whether to use Emacs or ELPA for it, plus any
>>> other tips that increase my chances.
>> This is surely documented somewhere.
>
>    [ Either provide a pointer better than "somewhere", or defer to the
>    future if you can't.]

OK.

> Where?

Check: http://www.emacswiki.org/emacs/ELPA#toc2

>> I guess it should go to ELPA, but you need to improve it.
>
> OK, I'll improve it. Once it's in ELPA, how do I maintain it? Can I keep
> using github for the upstream since I'm so familiar with it?

I guess, but it would require more work as you'd need to manually push it.
Perhaps Dmitry (of Company) could explain how he handles it.


>> (defvar darkroom-turns-on-visual-line-mode t
> See above.  I think providing a hook is better.  People can add this
> themselves 

Yes, I got rid of it.  You probably also need a hook when exiting.  Or the
functions in the hook are called with different argument when entering and
exiting the minor-mode.  (I did not reread your code).

>>> (defun darkroom-float-to-columns (f)
>> As above [docstring].
>
> Will do in the future. [ Is this essential? ]

Well, I'm going through your code.  Since my time is scare, I would rather
get a quick hint about what the function is doing.  I won't have to guess
everything then.

Take org-mode.  We have a bunch of weird little functions.  I do C-h f on
them.  If they have no docstring, I have to go a read the source (which I
probably don't care about).

>> Please add docstring, last argument.
>
> I made these internal variables (used the "--"), do I still need a
> docstring?

IMO: Yes.  I don't know if there's an establish consensus.

>>> (defun darkroom-visual-mode-maybe-enable ()
>> Docstring.  I don't understand the need of this feature.
>
> I've removed it, since it didn't work very well, but the idea is that a
> buffer in visual-line-mode (with soft wrapping of long lines), will
> always enter darkroom-mode with nice margins that perfectly center the
> text on the screen. A buffer with hard linebreaks (like this message) is
> not perfect for darkroom-mode, since the margins won't center it.

I agree.  Indeed if you can solve this issue it would be pretty cool.

> But I've added a utility function `darkroom-guess-margins' that can be
> set as the value for `darkroom-margins' and attempts to guess that. In
> the writing of this message, for example, where I `fill-pargraph' all
> the time, it has guessed the "correct" margins (see screenshot). In
> code, it normally defaults to 15% margins.

The screenshot looks nice.

> It's not perfect, and could be improved. Unfortunately, and more
> seriously, it doesn't work when the text scale is increase with
> `darkroom-text-scale-increase' set to anything but 0, because
> `window-width' doesn't know about text scaling
> apparently. `window-width' can return pixels, but then how can I know
> the pixel width of the current buffer's font? `frame-char-width' was
> promising, but also always returns a constant value.

To me, larger font would be essential.  And indeed, a problem is the
combination of auto-fill and larger font.  ATM I don't have a good idea on
how to solve this.

>>>   (cond ((and (not darkroom-mode) (= (count-windows) 1))
>> why count-windows?  Why would it not just use the buffer in focus?
>
> The idea in `darkroom-tentative-mode' here is that `darkroom-mode' is
> entered if and only if all but one window on the frame are deleted.
> 
>>> (define-minor-mode darkroom-tentative-mode
>>>   "Minor mode that enters `darkroom-mode' when all windws are deleted"
>> Again, this seems like a feature and I have no idea about it cause you
>> never explain the intended design.
>
> Well, minus typo I did very briefly. But it should be clearer now from
> the commits I did.

OK, as long as your document it, it's fine.

>> Hope it helps,
>
> It did. [ It did. ]
both of you are happy, that's good! 

—Rasmus

-- 
A page of history is worth a volume of logic