* Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS @ 2014-07-01 4:41 solidius4747 2014-07-01 7:44 ` James Freer ` (2 more replies) 0 siblings, 3 replies; 31+ messages in thread From: solidius4747 @ 2014-07-01 4:41 UTC (permalink / raw) To: help-gnu-emacs Hi everyone, I wrote part 3: http://tuhdo.github.io/emacs-tutor3.html It includes popular packages that people are using. If you are new to Emacs, it would be useful. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-01 4:41 Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS solidius4747 @ 2014-07-01 7:44 ` James Freer [not found] ` <mailman.4638.1404200703.1147.help-gnu-emacs@gnu.org> 2014-07-07 23:12 ` Emanuel Berg 2 siblings, 0 replies; 31+ messages in thread From: James Freer @ 2014-07-01 7:44 UTC (permalink / raw) To: help-gnu-emacs On 01/07/2014, solidius4747@gmail.com <solidius4747@gmail.com> wrote: > Hi everyone, > > I wrote part 3: http://tuhdo.github.io/emacs-tutor3.html > > It includes popular packages that people are using. If you are new to Emacs, > it would be useful. > I'm very grateful for the time you have spent although now after a couple of weeks I have learnt enough to be happy with. I've found using emacs-nox and forgetting about the gui is worthwhile and taking time to learn from the cheatsheet. It would be nice to have the 'mini manual' in pdf then one could print it out and read on the train (or similar times when one is away from the PC). thanks james ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.4638.1404200703.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] ` <mailman.4638.1404200703.1147.help-gnu-emacs@gnu.org> @ 2014-07-01 14:16 ` Emanuel Berg 2014-07-01 14:38 ` James Freer [not found] ` <mailman.4649.1404225527.1147.help-gnu-emacs@gnu.org> 0 siblings, 2 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-01 14:16 UTC (permalink / raw) To: help-gnu-emacs James Freer <jessejazza3.uk@gmail.com> writes: > I'm very grateful for the time you have spent > although now after a couple of weeks I have learnt > enough to be happy with. I've found using emacs-nox > and forgetting about the gui is worthwhile and taking > time to learn from the cheatsheet. It would be nice > to have the 'mini manual' in pdf then one could print > it out and read on the train (or similar times when > one is away from the PC). Do my ears deceive me?! Finally a guy with class! F*ing right! I haven't seen the particular document, though. I will read it tonight and probably get back to the OP with some comments. If you don't like to just print and read the HTML, you can use several tools to get it to PDF. You can use html2ps, and then ps2pdf - html2ps is in the repos, ps2pdf is part of ghostscript, which is likewise in the repos. (There are other ways to do this as well.) -- underground experts united: http://user.it.uu.se/~embe8573 ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-01 14:16 ` Emanuel Berg @ 2014-07-01 14:38 ` James Freer [not found] ` <mailman.4649.1404225527.1147.help-gnu-emacs@gnu.org> 1 sibling, 0 replies; 31+ messages in thread From: James Freer @ 2014-07-01 14:38 UTC (permalink / raw) To: Emanuel Berg; +Cc: help-gnu-emacs On Tue, 1 Jul 2014, Emanuel Berg wrote: > James Freer <jessejazza3.uk@gmail.com> writes: > >> I'm very grateful for the time you have spent >> although now after a couple of weeks I have learnt >> enough to be happy with. I've found using emacs-nox >> and forgetting about the gui is worthwhile and taking >> time to learn from the cheatsheet. It would be nice >> to have the 'mini manual' in pdf then one could print >> it out and read on the train (or similar times when >> one is away from the PC). > > Do my ears deceive me?! Finally a guy with class! > F*ing right! > > I haven't seen the particular document, though. I will > read it tonight and probably get back to the OP with > some comments. > > If you don't like to just print and read the HTML, you > can use several tools to get it to PDF. You can use > html2ps, and then ps2pdf - html2ps is in the repos, > ps2pdf is part of ghostscript, which is likewise in the > repos. (There are other ways to do this as well.) html2ps I'll have to look up I knew about ps2pdf and pdf2ps as I use it to send faxes. (yes fax still has a use). Or maybe I need to look at other methods. When I 'read on a train' - in truth I really meant that I like the pdf to print out, bind, and then use like a book for bedtime reading. keen beginner eh. james ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.4649.1404225527.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] ` <mailman.4649.1404225527.1147.help-gnu-emacs@gnu.org> @ 2014-07-08 8:36 ` solidius4747 2014-07-08 15:09 ` Emanuel Berg 0 siblings, 1 reply; 31+ messages in thread From: solidius4747 @ 2014-07-08 8:36 UTC (permalink / raw) To: help-gnu-emacs Vào 21:38:24 UTC+7 Thứ ba, ngày 01 tháng bảy năm 2014, jessejazza đã viết: > On Tue, 1 Jul 2014, Emanuel Berg wrote: > > > > > James Freer <jessejazza3.uk@gmail.com> writes: > > > > > >> I'm very grateful for the time you have spent > > >> although now after a couple of weeks I have learnt > > >> enough to be happy with. I've found using emacs-nox > > >> and forgetting about the gui is worthwhile and taking > > >> time to learn from the cheatsheet. It would be nice > > >> to have the 'mini manual' in pdf then one could print > > >> it out and read on the train (or similar times when > > >> one is away from the PC). > > > > > > Do my ears deceive me?! Finally a guy with class! > > > F*ing right! > > > > > > I haven't seen the particular document, though. I will > > > read it tonight and probably get back to the OP with > > > some comments. > > > > > > If you don't like to just print and read the HTML, you > > > can use several tools to get it to PDF. You can use > > > html2ps, and then ps2pdf - html2ps is in the repos, > > > ps2pdf is part of ghostscript, which is likewise in the > > > repos. (There are other ways to do this as well.) > > > > html2ps > > I'll have to look up > > > > I knew about ps2pdf and pdf2ps as I use it to send faxes. (yes fax still has > > a use). Or maybe I need to look at other methods. > > > > When I 'read on a train' - in truth I really meant that I like the pdf to print > > out, bind, and then use like a book for bedtime reading. keen beginner eh. > > > > james I'm glad that you like my tutorial. I'm working on how to generate a pdf document with org-mode. Not sure how many pages my "mini manual" actually consumes. I didn't intend it to be a book in the first place. Vào 06:12:10 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết: > solidius4747@gmail.com writes: > > > > > I wrote part 3: > > > http://tuhdo.github.io/emacs-tutor3.html > > > > > > It includes popular packages that people are > > > using. If you are new to Emacs, it would be useful. > > > > I wouldn't call that tutorial "mini"! > > > > It is clear you put a very big effort into this. You > > should get a medal, or some part of the gold stashed in > > IET, the International Emacs Treasury (if there is > > one). > > > > But, this makes me think, did you experience any > > shortcomings or "gaps" in the official Emacs manual? > > Perhaps you could integrate your project with it, > > somehow. If not, the official Emacs people should put a > > link to your project from the official site, at least, > > if they didn't already. > > > > Feedback on the material itself: the part on MELPA, > > what I can see it misses one essential part, namely how > > to *submit* code: both how that is done in practice, > > and guidelines on the Elisp itself (or references, if > > you don't feel like writing this all over). > > > > Keep it up! > > > > -- > > underground experts united Thanks! As I stated in Part 1 in "Why I wrote this guide" section, it is because I feel the Emacs manual is designed to be more like a reference material than a beginner material. It also does not mention about popular 3rd party packages, and popular package archives like MELPA. Where should new users to Emacs find this information? They will have to waste time to rediscover packages that people used long ago. I want to get productive with Emacs as fast as possible. Telling people to read the whole Emacs Lisp manual before able to customizing/extending Emacs is likely to push them away from Emacs. As for submitting code to MELPA, I don't think it's necessary to include in the guide, because clearly the targeted audience is beginners who just start their journey with customizing/extending Emacs. It's unlikely they will roll a package on their own after finishing the guide anyway. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 8:36 ` solidius4747 @ 2014-07-08 15:09 ` Emanuel Berg 2014-07-08 16:18 ` Drew Adams ` (3 more replies) 0 siblings, 4 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-08 15:09 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: > As I stated in Part 1 in "Why I wrote this guide" > section, it is because I feel the Emacs manual is > designed to be more like a reference material than a > beginner material. I only have a very old version of the manual - Emacs 18, I think - but I read that twice. It wasn't difficult to understand but I noticed there were gaps in it when I compared how I used Emacs. There was no mention of Gnus and I don't remember if RMAIL was mentioned, for example, but there were material on the message-mode, perhaps to be used between Unix boxes on an intranet (?) - of course, if those things weren't around then, they couldn't have been included - but as for being a reference, I don't remember it being too difficult to digest, on the contrary I remember it being pleasant to read (big sheets, wide margins, clear and normal language, and so on). > It also does not mention about popular 3rd party > packages, and popular package archives like MELPA. It is not only the manual who is quiet about MELPA. I didn't know of it until recently, when I learned about it - ironically - on gnu.emacs.sources. In this book @Book{cameron, author = {Cameron and Elliot and Loy and Raymond and Rosenblatt}, title = {Learning GNU Emacs}, publisher = {O'Reilly}, year = 2004, ISBN = {0-596-00648-9}, edition = {3rd edition}} there is a very short chapter on packages and online, unofficial repositories, but it doesn't say how to use it and it doesn't mention MELPA or even ELPA. So, all the more reason (in my mind) for you to mention it in more detail, or at least to provide a reference to "how to broadcast" as that is as vital a part as is downloading/installing. It just seems clear to me. > Where should new users to Emacs find this > information? They will have to waste time to > rediscover packages that people used long ago. Right, that's always the case. However, just knowing about MELPA won't have people discovering what they want instantly. Of course, first they must know what they want, which always takes time, and is natural and nothing that we should (could) influence (to any extent anyway). But the second part is: finding what they want. So how do you search MELPA? And how do you know what to search for, if you terminology is different from the person who wrote the package? Great things to discuss here, as well as to include... > I want to get productive with Emacs as fast as > possible. Everything in time... > Telling people to read the whole Emacs Lisp manual > before able to customizing/extending Emacs is likely > to push them away from Emacs. We should of course never tell anyone to read the manual, and especially not the whole Elisp manual :) We can post URLs. Best way is for course to do that, but also explain how it relates to the particular problem, and even support example Elisp. But sometimes there isn't the energy, time or will to do that, and then a HTTP manual in small chapters is great so you at least can give the URL. > As for submitting code to MELPA, I don't think it's > necessary to include in the guide, because clearly > the targeted audience is beginners who just start > their journey with customizing/extending Emacs. It's > unlikely they will roll a package on their own after > finishing the guide anyway. Well, I disagree here. First, the beginners will use your tutorial, yes, but that's not it. They will also write Elisp and configure Emacs and use Emacs and the online help. They are likely to also come across the Emacs manual, the Elisp manual, perhaps even the Gnus manual, and of course the EmacsWiki if they happen to Google problems (very likely). You yourself said MELPA didn't get enough attention (and I agree), so if the readers come across it in your book, at some point they will ask - "how do I use MELPA in a more advanced way: searching, filtering, submitting?" - at that point, if the readers first came across it in your book, they will instinctively reach for that book. If they read about it somewhere else, they'll go for that source, of course. But we (you) cannot influence that, can be? Better make your own source as complete as possible. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* RE: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 15:09 ` Emanuel Berg @ 2014-07-08 16:18 ` Drew Adams 2014-07-08 16:45 ` solidius4747 ` (2 subsequent siblings) 3 siblings, 0 replies; 31+ messages in thread From: Drew Adams @ 2014-07-08 16:18 UTC (permalink / raw) To: Emanuel Berg, help-gnu-emacs > I only have a very old version of the manual - Emacs > 18, I think - but I read that twice. Really? You have _only_ an old version? If you have a version of Emacs more recent than 18 then you should also have its manual, as part of Emacs. (And if you do have the manual for your version then you should be reading that, not (just) the Emacs 18 manual.) Even if, for some reason, you do not have a more recent manual than 18, recent manuals are available online. For example: http://www.gnu.org/software/emacs/manual/. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 15:09 ` Emanuel Berg 2014-07-08 16:18 ` Drew Adams @ 2014-07-08 16:45 ` solidius4747 2014-07-08 21:36 ` Emanuel Berg 2014-08-25 14:05 ` Jude DaShiell 2014-07-08 18:56 ` Robert Thorpe [not found] ` <mailman.5091.1404836351.1147.help-gnu-emacs@gnu.org> 3 siblings, 2 replies; 31+ messages in thread From: solidius4747 @ 2014-07-08 16:45 UTC (permalink / raw) To: help-gnu-emacs Vào 22:09:49 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết: > I only have a very old version of the manual - Emacs > > 18, I think - but I read that twice. It wasn't > > difficult to understand but I noticed there were gaps > > in it when I compared how I used Emacs. There was no > > mention of Gnus and I don't remember if RMAIL was > > mentioned, for example, but there were material on the > > message-mode, perhaps to be used between Unix boxes on > > an intranet (?) - of course, if those things weren't > > around then, they couldn't have been included - but as > > for being a reference, I don't remember it being too > > difficult to digest, on the contrary I remember it > > being pleasant to read (big sheets, wide margins, clear > > and normal language, and so on). > > > > > It also does not mention about popular 3rd party > > > packages, and popular package archives like MELPA. > > > > It is not only the manual who is quiet about MELPA. I > > didn't know of it until recently, when I learned about > > it - ironically - on gnu.emacs.sources. > > > > In this book > > > > @Book{cameron, > > author = {Cameron and Elliot and Loy and Raymond and Rosenblatt}, > > title = {Learning GNU Emacs}, > > publisher = {O'Reilly}, > > year = 2004, > > ISBN = {0-596-00648-9}, > > edition = {3rd edition}} > > > > there is a very short chapter on packages and online, > > unofficial repositories, but it doesn't say how to use > > it and it doesn't mention MELPA or even ELPA. > > > > So, all the more reason (in my mind) for you to mention > > it in more detail, or at least to provide a reference > > to "how to broadcast" as that is as vital a part as is > > downloading/installing. It just seems clear to me. > The recent GNU Emacs Manual is more than 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf It includes packages like Semantic, EDE, Calc, GUD... (I am using these packages myself). That's a lot of features. Certainly, users won't need to learn of those to be productive. It's likely that users usually read cover from cover, so they will be distracted by unnecessary stuffs not needed at the moment. The exported PDF of part 1 is only 43 pages long and part 3 is 83 pages long. Certainly mini compared to the actual manual. I also added screencasts to demonstrate what Emacs is capable of. I want to ensure the new users that learning Emacs worth their time. I also explicitly stated that the official Emacs manual is the next place they should look for if they want to get the most of Emacs. My manual only provides a starting point. > Right, that's always the case. However, just knowing > > about MELPA won't have people discovering what they > > want instantly. Of course, first they must know what > > they want, which always takes time, and is natural and > > nothing that we should (could) influence (to any extent > > anyway). But the second part is: finding what they > > want. So how do you search MELPA? And how do you know > > what to search for, if you terminology is different > > from the person who wrote the package? Great things to > > discuss here, as well as to include... MELPA is really useful. It helped me to discover many useful packages and ease package management. Before that, I added packages as submodules in my .emacs.d git repo. I think once users know MELPA, even if they do not know what they want, they will explore the packages, install and play with it - like I did - and discover features not available in other editors; for example, Helm, Magit, undo-tree... > We should of course never tell anyone to read the > > manual, and especially not the whole Elisp manual :) We > > can post URLs. Best way is for course to do that, but > > also explain how it relates to the particular problem, > > and even support example Elisp. But sometimes there > > isn't the energy, time or will to do that, and then a > > HTTP manual in small chapters is great so you at least > > can give the URL. I did provide it in part 3, not to the manual, but encourage new users to directly use Emacs for looking up functions and stuffs, as you can see in the section "Just enough Emacs Lisp" for each listed function. But probably I will provide a link to the function in the official Elisp manual, so they can compare and contrast. > Well, I disagree here. First, the beginners will use > > your tutorial, yes, but that's not it. They will also > > write Elisp and configure Emacs and use Emacs and the > > online help. They are likely to also come across the > > Emacs manual, the Elisp manual, perhaps even the Gnus > > manual, and of course the EmacsWiki if they happen to > > Google problems (very likely). You yourself said MELPA > > didn't get enough attention (and I agree), so if the > > readers come across it in your book, at some point they > > will ask - "how do I use MELPA in a more advanced way: > > searching, filtering, submitting?" - at that point, if > > the readers first came across it in your book, they > > will instinctively reach for that book. If they read > > about it somewhere else, they'll go for that source, of > > course. But we (you) cannot influence that, can be? > > Better make your own source as complete as possible. Yes, I know. That's the route I worked through when I was new to Emacs. But I still want new users to be productive with Emacs as possible, with minimal Elisp. To be honest, I'm not an expert with Emacs Lisp; I'm still learning (I actually want to be proficient with Common Lisp first) and I only have limited experience with Racket from some Coursera courses ("Introduction to Systematic Design" - which uses the book How to Design Program and "Programming Languages" that I wrote a small evaluator for a made up language). I always encourage users to seek help from the official manual and especially, within Emacs itself, in all of my articles. In part 3, I only want to introduce enough Emacs Lisp that new users can feel comfortable with using MELPA to add package for extending Emacs, rather than taking the hard route, that is actually learn and write Elisp. I think, after new users use various Emacs packages from the community comfortable, they will see the power of Emacs and have an interest in learning Elisp, just like I did. That's why I listed many popular and useful packages, one by one in this part, along with how to set up the packages properly to start using it. I believe, by repeating adding packages and Elisp code configuration, new users will get comfortable with Elisp and extending Emacs in general. My goal is to have an interested-in-Emacs reader to get what I demonstrated in part 1 in about a month or less. As for searching and filtering packages using the package manager, I will add it. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 16:45 ` solidius4747 @ 2014-07-08 21:36 ` Emanuel Berg 2014-07-09 2:41 ` solidius4747 2014-08-25 14:05 ` Jude DaShiell 1 sibling, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-08 21:36 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: > The recent GNU Emacs Manual is more than 600 pages > long: > http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf > > It includes packages like Semantic, EDE, Calc, > GUD... (I am using these packages myself). That's a > lot of features. Certainly, users won't need to learn > of those to be productive. It depends what packages and what users, and what they do. > It's likely that users usually read cover from cover I think that is very unlikely for the majority of Emacs users. But it is not a bad idea to do - on the contrary... > so they will be distracted by unnecessary stuffs not > needed at the moment. The exported PDF of part 1 is > only 43 pages long and part 3 is 83 pages > long. Certainly mini compared to the actual manual. I think "mini" is 1-3 pages. But you wrote it, you name it. of course. > I also added screencasts to demonstrate what Emacs is > capable of. Screencast = screenshot or dump? If so, that's great. Those are very informative for the trained eye and there is no coincidence that computer magazines are always littered with those. In the accursed computer science world, they don't do that a lot (at all) but there is actually no one stopping you, so just do it where it helps. One thing with the computer magazines though, they tend to include very small screenshots, often you cannot see. I think screenshots should be half a page or at least one fourth a page to be truly telling. Often it doesn't help to litter them with arrows and boxes. It is better to add this in the description beneath the image, with "down left" (etc.) instead of arrows and the like. > I want to ensure the new users that learning Emacs > worth their time. I also explicitly stated that the > official Emacs manual is the next place they should > look for if they want to get the most of Emacs. My > manual only provides a starting point. Yeah, I suppose it isn't wrong to think up some logical order but in reality I don't think it works that way most of the time. I don't think people start reading one thing, completes it, then the next thing at a somewhat higher level, until they master it. They read some, experiment some, use the help some, Google some, ... > MELPA is really useful. It helped me to discover many > useful packages and ease package management. Before > that, I added packages as submodules in my .emacs.d > git repo. I think once users know MELPA, even if they > do not know what they want, they will explore the > packages, install and play with it - like I did - and > discover features not available in other editors; for > example, Helm, Magit, undo-tree... If they know how to do that... And you have a good opportunity to teach them what you know. > As for searching and filtering packages using the > package manager, I will add it. Yeah? :) Cool. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 21:36 ` Emanuel Berg @ 2014-07-09 2:41 ` solidius4747 2014-07-09 8:52 ` Robert Thorpe 2014-07-09 17:11 ` Emanuel Berg 0 siblings, 2 replies; 31+ messages in thread From: solidius4747 @ 2014-07-09 2:41 UTC (permalink / raw) To: help-gnu-emacs Vào 04:36:55 UTC+7 Thứ tư, ngày 09 tháng bảy năm 2014, Emanuel Berg đã viết: > It depends what packages and what users, and what they > > do. Well I was wrong. The Emacs manual does not cover those packages. Over 600 pages dedicate to Emacs alone. > I think that is very unlikely for the majority of Emacs > > users. But it is not a bad idea to do - on the > > contrary... Yes I know since the official manuals are huge. But if they have smaller and simpler books (i.e. how to books), they will usually read cover by cover. And when I say reading the whole book, I mean they actually spend time playing with Emacs, but use the book as the primary learning source most of the time, similar to someone leare a new programming language with a book. > Screencast = screenshot or dump? If so, that's > > great. Those are very informative for the trained eye > > and there is no coincidence that computer magazines are > > always littered with those. In the accursed computer > > science world, they don't do that a lot (at all) but > > there is actually no one stopping you, so just do it > > where it helps. One thing with the computer magazines > > though, they tend to include very small screenshots, > > often you cannot see. I think screenshots should be > > half a page or at least one fourth a page to be truly > > telling. Often it doesn't help to litter them with > > arrows and boxes. It is better to add this in the > > description beneath the image, with "down left" (etc.) > > instead of arrows and the like. Screencast is a recording of screen using video or image like GIF. I used GIF for demonstrating what Emacs looks like when it has 3rd party packages and properly configured. For example, I showed users that Emacs is also capable of context-sensitive completion for C/C++, GUD GDB provides an easy to use and interactive user interface, with colors, Magit... > Yeah, I suppose it isn't wrong to think up some logical > > order but in reality I don't think it works that way > > most of the time. I don't think people start reading > > one thing, completes it, then the next thing at a > > somewhat higher level, until they master it. They read > > some, experiment some, use the help some, Google some, > > ... Yes, that's why I wrote this tutorial. I want users to collect experience here and there from various sources. That's why I wrote part 3, a collection of useful and popular packages, with useful configurations, to prevent users from rediscover from somewhere. In part 1, I provided exercises in most sections for users to practice. The exercises are common use cases for Emacs features, i.e. why should we save window configurations in register and how to use it effectively. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-09 2:41 ` solidius4747 @ 2014-07-09 8:52 ` Robert Thorpe 2014-07-09 17:11 ` Emanuel Berg 1 sibling, 0 replies; 31+ messages in thread From: Robert Thorpe @ 2014-07-09 8:52 UTC (permalink / raw) To: solidius4747; +Cc: help-gnu-emacs solidius4747@gmail.com writes: > Vào 04:36:55 UTC+7 Thứ tư, ngày 09 tháng bảy năm 2014, Emanuel Berg đã viết: > >> It depends what packages and what users, and what they >> >> do. > > Well I was wrong. The Emacs manual does not cover those packages. Over 600 pages dedicate to Emacs alone. They aren't covered in the Emacs manual itself, but they are covered in the *Manual Set* you get with Emacs which consists of ~50 manuals. Generally, large packages have their own manual and smaller ones are within the Emacs manual. BR, Robert Thorpe ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-09 2:41 ` solidius4747 2014-07-09 8:52 ` Robert Thorpe @ 2014-07-09 17:11 ` Emanuel Berg 1 sibling, 0 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-09 17:11 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: > Screencast is a recording of screen using video or > image like GIF. I used GIF for demonstrating what > Emacs looks like when it has 3rd party packages and > properly configured. For example, I showed users that > Emacs is also capable of context-sensitive completion > for C/C++, GUD GDB provides an easy to use and > interactive user interface, with colors, Magit... Yes, I think this is what I call screenshot or dump. In this context, let me mention I found a cool way to do it for Linux VT/tty/console users. In another terminal, execute the following zsh function (with the assumption that Emacs is in /dev/tty1) - dumpemacs () { file=$1.png sudo fbgrab -c 1 $file sudo chown $USER $file } I don't know why you have to do it as superuser and IIRC it didn't help to 'chmod +s' - also, perhaps the group should be changed as well - but anyway, the screenshot looks great - here is a screenshot of me writing this: http://user.it.uu.se/~embe8573/screencast.png -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 16:45 ` solidius4747 2014-07-08 21:36 ` Emanuel Berg @ 2014-08-25 14:05 ` Jude DaShiell 1 sibling, 0 replies; 31+ messages in thread From: Jude DaShiell @ 2014-08-25 14:05 UTC (permalink / raw) To: solidius4747; +Cc: help-gnu-emacs I wasn't even aware of ses until earlier today and found that as a built-in looking through m-x list-packages. Fortunately emacs has that available since oleo won't build on this amd K8 athelon I have. A built-in that's coming in the next version of emacs will be eww and for those of us on command line level of linux (no g.u.i.) by preference, masquerrade mode from what I've read over on the emacspeak list may get us better web content from several sites that restrict content just because a text browser is in use. One real useful tool I found with emacs that's also built-in is orgmode. That has spreadsheet capacity, but implementation in terms of content of fmtline's to my mind is abstruse. On Tue, 8 Jul 2014, solidius4747@gmail.com wrote: The forms built-in will probably be very useful but this is probably at an intermediate level. > V?o 22:09:49 UTC+7 Th? ba, ng?y 08 th?ng b?y n?m 2014, Emanuel Berg ?? > vi?t: > > > I only have a very old version of the manual - Emacs > > > > 18, I think - but I read that twice. It wasn't > > > > difficult to understand but I noticed there were gaps > > > > in it when I compared how I used Emacs. There was no > > > > mention of Gnus and I don't remember if RMAIL was > > > > mentioned, for example, but there were material on the > > > > message-mode, perhaps to be used between Unix boxes on > > > > an intranet (?) - of course, if those things weren't > > > > around then, they couldn't have been included - but as > > > > for being a reference, I don't remember it being too > > > > difficult to digest, on the contrary I remember it > > > > being pleasant to read (big sheets, wide margins, clear > > > > and normal language, and so on). > > > > > > > > > It also does not mention about popular 3rd party > > > > > packages, and popular package archives like MELPA. > > > > > > > > It is not only the manual who is quiet about MELPA. I > > > > didn't know of it until recently, when I learned about > > > > it - ironically - on gnu.emacs.sources. > > > > > > > > In this book > > > > > > > > @Book{cameron, > > > > author = {Cameron and Elliot and Loy and Raymond and Rosenblatt}, > > > > title = {Learning GNU Emacs}, > > > > publisher = {O'Reilly}, > > > > year = 2004, > > > > ISBN = {0-596-00648-9}, > > > > edition = {3rd edition}} > > > > > > > > there is a very short chapter on packages and online, > > > > unofficial repositories, but it doesn't say how to use > > > > it and it doesn't mention MELPA or even ELPA. > > > > > > > > So, all the more reason (in my mind) for you to mention > > > > it in more detail, or at least to provide a reference > > > > to "how to broadcast" as that is as vital a part as is > > > > downloading/installing. It just seems clear to me. > > > > The recent GNU Emacs Manual is more than 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf > > It includes packages like Semantic, EDE, Calc, GUD... (I am using these packages myself). That's a lot of features. Certainly, users won't need to learn of those to be productive. It's likely that users usually read cover from cover, so they will be distracted by unnecessary stuffs not needed at the moment. The exported PDF of part 1 is only 43 pages long and part 3 is 83 pages long. Certainly mini compared to the actual manual. I also added screencasts to demonstrate what Emacs is capable of. I want to ensure the new users that learning Emacs worth their time. I also explicitly stated that the official Emacs manual is the next place they should look for if they want to get the most of Emacs. My manual only provides a starting point. > > > Right, that's always the case. However, just knowing > > > > about MELPA won't have people discovering what they > > > > want instantly. Of course, first they must know what > > > > they want, which always takes time, and is natural and > > > > nothing that we should (could) influence (to any extent > > > > anyway). But the second part is: finding what they > > > > want. So how do you search MELPA? And how do you know > > > > what to search for, if you terminology is different > > > > from the person who wrote the package? Great things to > > > > discuss here, as well as to include... > > MELPA is really useful. It helped me to discover many useful packages and ease package management. Before that, I added packages as submodules in my .emacs.d git repo. I think once users know MELPA, even if they do not know what they want, they will explore the packages, install and play with it - like I did - and discover features not available in other editors; for example, Helm, Magit, undo-tree... > > > > We should of course never tell anyone to read the > > > > manual, and especially not the whole Elisp manual :) We > > > > can post URLs. Best way is for course to do that, but > > > > also explain how it relates to the particular problem, > > > > and even support example Elisp. But sometimes there > > > > isn't the energy, time or will to do that, and then a > > > > HTTP manual in small chapters is great so you at least > > > > can give the URL. > > I did provide it in part 3, not to the manual, but encourage new users to directly use Emacs for looking up functions and stuffs, as you can see in the section "Just enough Emacs Lisp" for each listed function. But probably I will provide a link to the function in the official Elisp manual, so they can compare and contrast. > > > > Well, I disagree here. First, the beginners will use > > > > your tutorial, yes, but that's not it. They will also > > > > write Elisp and configure Emacs and use Emacs and the > > > > online help. They are likely to also come across the > > > > Emacs manual, the Elisp manual, perhaps even the Gnus > > > > manual, and of course the EmacsWiki if they happen to > > > > Google problems (very likely). You yourself said MELPA > > > > didn't get enough attention (and I agree), so if the > > > > readers come across it in your book, at some point they > > > > will ask - "how do I use MELPA in a more advanced way: > > > > searching, filtering, submitting?" - at that point, if > > > > the readers first came across it in your book, they > > > > will instinctively reach for that book. If they read > > > > about it somewhere else, they'll go for that source, of > > > > course. But we (you) cannot influence that, can be? > > > > Better make your own source as complete as possible. > > Yes, I know. That's the route I worked through when I was new to Emacs. But I still want new users to be productive with Emacs as possible, with minimal Elisp. To be honest, I'm not an expert with Emacs Lisp; I'm still learning (I actually want to be proficient with Common Lisp first) and I only have limited experience with Racket from some Coursera courses ("Introduction to Systematic Design" - which uses the book How to Design Program and "Programming Languages" that I wrote a small evaluator for a made up language). > > I always encourage users to seek help from the official manual and especially, within Emacs itself, in all of my articles. In part 3, I only want to introduce enough Emacs Lisp that new users can feel comfortable with using MELPA to add package for extending Emacs, rather than taking the hard route, that is actually learn and write Elisp. I think, after new users use various Emacs packages from the community comfortable, they will see the power of Emacs and have an interest in learning Elisp, just like I did. That's why I listed many popular and useful packages, one by one in this part, along with how to set up the packages properly to start using it. I believe, by repeating adding packages and Elisp code configuration, new users will get comfortable with Elisp and extending Emacs in gen eral. My goal is to have an interested-in-Emacs reader to get what I demonstrated in part 1 in about a month or less. > > As for searching and filtering packages using the package manager, I will add it. > > jude <jdashiel@shellworld.net> ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 15:09 ` Emanuel Berg 2014-07-08 16:18 ` Drew Adams 2014-07-08 16:45 ` solidius4747 @ 2014-07-08 18:56 ` Robert Thorpe [not found] ` <mailman.5091.1404836351.1147.help-gnu-emacs@gnu.org> 3 siblings, 0 replies; 31+ messages in thread From: Robert Thorpe @ 2014-07-08 18:56 UTC (permalink / raw) To: Emanuel Berg; +Cc: help-gnu-emacs Emanuel Berg <embe8573@student.uu.se> writes: > solidius4747@gmail.com writes: > ... > > I only have a very old version of the manual - Emacs > 18, I think - but I read that twice. It wasn't > difficult to understand but I noticed there were gaps > in it when I compared how I used Emacs. There was no > mention of Gnus and I don't remember if RMAIL was > mentioned, for example, but there were material on the > message-mode, perhaps to be used between Unix boxes on > an intranet (?) - of course, if those things weren't > around then, they couldn't have been included - but as > for being a reference, I don't remember it being too > difficult to digest, on the contrary I remember it > being pleasant to read (big sheets, wide margins, clear > and normal language, and so on). I recommend using a new version of the Emacs manual set. The last version of Emacs 18 was released more than 21 years ago. The current manual describes RMAIL in detail. A separate manual describes GNUS, that manual is part of the set. "Message-mode" is the mode for composing email and newsgroup posts that comes with GNUS. It's used by GNUS, RMAIL and several other programs. It's frequently used, I'm using it now, that's why it's included in the manual set. Of-course reading an old manual is still useful, many things haven't changed. Most of the manuals provide basic help on using a feature *and* more advanced info. So, the manuals can be read as a reference, or read selectively. I'm in the process of re-reading the Emacs manual myself. I've found quite a lot of useful stuff. This isn't a criticism of solidius4747's tutorial. I haven't had a chance to read it yet, so I can't comment. I agree that there are many things that should be treated in the manual that aren't there. BR, Rob ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.5091.1404836351.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] ` <mailman.5091.1404836351.1147.help-gnu-emacs@gnu.org> @ 2014-07-08 21:21 ` Emanuel Berg 2014-07-09 8:44 ` Robert Thorpe ` (2 more replies) 0 siblings, 3 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-08 21:21 UTC (permalink / raw) To: help-gnu-emacs Drew Adams <drew.adams@oracle.com> writes: >> I only have a very old version of the manual - Emacs >> 18, I think - but I read that twice. > > Really? You have _only_ an old version? Yes. It is actually a very cool item. The pages are in A4 and it has a light-blue cover and dark-blue heft. A big section is about the GNU philosophy. It is in questions and answers, and in the questions there is criticism of the whole idea. That's brave! You get the feeling it was much more alive back then and not just a set of axioms, a "stamp" you accept in principle but nonetheless ignore in practice, eager to get to the technology part of whatever documentation or piece of source. > If you have a version of Emacs more recent than 18 > then you should also have its manual, as part of > Emacs. Well, this is actually not the case as was recently discussed in another thread. With 'info Emacs' I get the Emacs FAQ, not the manual. There was mention of some bad blood between the Emacs people and the Debian people, who considered the Emacs manual non-free (no idea why). I have of course access to the non-free repos, but there is no emacs-doc like with gcc which documentation (the manpage) Debian also has issues with. Wait - I think I got it, it is probably emacs24-common-non-dfsg, right? DFSG is "Debian Free Software Guidelines". > (And if you do have the manual for your version then > you should be reading that, not (just) the Emacs 18 > manual.) Well, should and should... I'm not going to read it on the screen by the computer, that's for sure. > Even if, for some reason, you do not have a more > recent manual than 18, recent manuals are available > online. For example: > http://www.gnu.org/software/emacs/manual/ Yes, this seems to be the PDF, ready to print: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf Alright, I'll do it. I know you contributed to it so I'll just blame you for everything I don't like. But actually I think I'll like all or most of it. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 21:21 ` Emanuel Berg @ 2014-07-09 8:44 ` Robert Thorpe 2014-07-10 2:11 ` Bob Proulx [not found] ` <mailman.5163.1404958319.1147.help-gnu-emacs@gnu.org> 2 siblings, 0 replies; 31+ messages in thread From: Robert Thorpe @ 2014-07-09 8:44 UTC (permalink / raw) To: Emanuel Berg; +Cc: help-gnu-emacs Emanuel Berg <embe8573@student.uu.se> writes: > Drew Adams <drew.adams@oracle.com> writes: ... > Wait - I think I got it, it is probably > emacs24-common-non-dfsg, right? DFSG is "Debian Free > Software Guidelines". That's right. As I mentioned when we were talking about this last week. BR, Robert Thorpe ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 21:21 ` Emanuel Berg 2014-07-09 8:44 ` Robert Thorpe @ 2014-07-10 2:11 ` Bob Proulx [not found] ` <mailman.5163.1404958319.1147.help-gnu-emacs@gnu.org> 2 siblings, 0 replies; 31+ messages in thread From: Bob Proulx @ 2014-07-10 2:11 UTC (permalink / raw) To: help-gnu-emacs Emanuel Berg wrote: > Well, this is actually not the case as was recently > discussed in another thread. With 'info Emacs' I get > the Emacs FAQ, not the manual. There was mention of > some bad blood between the Emacs people and the Debian > people, who considered the Emacs manual non-free (no idea > why). The problem can be summarized as the manual used a non-free license with the hope that it would encourage a print shop to print and sell physical copies of the manual. But the result is one of unintended consequences. Instead of encouraging documentation proliferation it has the opposite of restricting the flow of it. Please see this for the details of the reasons. http://www.debian.org/vote/2006/vote_001 > I have of course access to the non-free repos, but > there is no emacs-doc like with gcc which documentation > (the manpage) Debian also has issues with. > > Wait - I think I got it, it is probably > emacs24-common-non-dfsg, right? DFSG is "Debian Free > Software Guidelines". Right. emacs24-common-non-dfsg is the package. Simply install it from the non-free section. It is sad that two of the most freedom promoting organizations are at opposite ends of this documentation issue. Both are principled. But with slightly different principles. > Well, should and should... I'm not going to read it on > the screen by the computer, that's for sure. I do read most of the documentation on the screen. However I don't find it as good as a printed book. Therefore I have a *lot* of printed books! > Alright, I'll do it. I know you contributed to it so > I'll just blame you for everything I don't like. But > actually I think I'll like all or most of it. I am still chuckling over this comment of yours. Nicely done. :-) Bob ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.5163.1404958319.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] ` <mailman.5163.1404958319.1147.help-gnu-emacs@gnu.org> @ 2014-07-10 22:16 ` Emanuel Berg 2014-07-12 14:52 ` Javier 0 siblings, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-10 22:16 UTC (permalink / raw) To: help-gnu-emacs Bob Proulx <bob@proulx.com> writes: > The problem can be summarized as the manual used a > non-free license with the hope that it would > encourage a print shop to print and sell physical > copies of the manual. Too bad that didn't work. I have been to tons of public libraries and they basically mimic the bookstores, only their books are older and with "annotations". Some of the books are still good, but most are those "Learn Brain Surgery in 24 Days, the Fun and Easy Way" - if you don't get provoked by such obvious nonsense, those books can be helpful - still, if you have done something for but one or two years, those are typically hopelessly "broad" for your purposes. To find the Emacs manual at such a bookshelf would be a very pleasant surprise! > But the result is one of unintended consequences. > Instead of encouraging documentation proliferation it > has the opposite of restricting the flow of it. > > Please see this for the details of the reasons. > > http://www.debian.org/vote/2006/vote_001 Thanks, but that was so technical. I don't understand the issue. But I suppose if you want to have a movement and you put up rules - and some other part of the movement that basically share your views, if they do the same - what will eventually happen if those rules are many (and specific), some of the will clash and probably that's what happened here. > I do read most of the documentation on the screen. > However I don't find it as good as a printed book. > Therefore I have a *lot* of printed books! Yes, documentation on-screen is great in the man page sense, the online Emacs help sense, when you want to know some part of the interface. If you do Elisp for some time, and then switch to C, you feel like an idiot having to Google stuff because the interface isn't available (though some of the C is in the manpages). But there is actually nothing that stops anyone from writing C (interface) documentation that would work more or less like the Elisp one. On the other hand, to you read (page up, page down) on-screen I don't like. The computer should boost activity, not consumption of material like those pads that have enslaved the, eh, "kids" those days. That's why I also like books to be at a different "pace" than on-screen material. I appreciate when they tell the back story, some jokes, whatever, not just what you need to know to solve an immediate problem. If the pace of the book is right, you get into a pleasant state yourselves. Books are great. I wish I had a job where I could turn in lists of books to my boss, and he'd buy them for me... >> Alright, I'll do it. I know you contributed to it so >> I'll just blame you for everything I don't like. But >> actually I think I'll like all or most of it. > > I am still chuckling over this comment of yours. > Nicely done. :-) Ha ha, stupid jokes aside, if there are any newcomers to the Emacs or FOSS world lurking (I hope so!) who haven't figured it out, let me say writing documentation is time-consuming, difficult, it is an unsung business, and it can be frustrating as there are morons around talking trash about the software yet refusing to read the documentation, that would instantly solve whatever mess they're in. So the people who do documentation deserves cred and nothing else. As for the quality, there can be no better source for information than the official manual of a long-lived FOSS project. The reason is, the same material has been worked up by so many people, age in, age out - you know how commercial books boast "3rd edition" and so on? But to our manuals, there as been three million revisions - it is just a massacre by comparison. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-10 22:16 ` Emanuel Berg @ 2014-07-12 14:52 ` Javier 2014-07-12 19:49 ` Emanuel Berg 2014-07-13 1:40 ` Robert Thorpe 0 siblings, 2 replies; 31+ messages in thread From: Javier @ 2014-07-12 14:52 UTC (permalink / raw) To: help-gnu-emacs Emanuel Berg <embe8573@student.uu.se> wrote: > Yes, documentation on-screen is great in the man page > sense, the online Emacs help sense, when you want to > know some part of the interface. If you do Elisp for > some time, and then switch to C, you feel like an idiot > having to Google stuff because the interface isn't > available (though some of the C is in the > manpages). But there is actually nothing that stops > anyone from writing C (interface) documentation that > would work more or less like the Elisp one. It would be an interesting project to convert those documents to texinfo format. With Python it is possible to convert the documentation (sphinx doc generator) of Python and its libraries to texinfo, and documentation can be gerated automatically for any python project to texinfo. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-12 14:52 ` Javier @ 2014-07-12 19:49 ` Emanuel Berg 2014-07-12 23:30 ` Javier 2014-07-13 1:40 ` Robert Thorpe 1 sibling, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-12 19:49 UTC (permalink / raw) To: help-gnu-emacs Javier <nospam@nospam.com> writes: >> Yes, documentation on-screen is great in the man >> page sense, the online Emacs help sense, when you >> want to know some part of the interface. If you do >> Elisp for some time, and then switch to C, you feel >> like an idiot having to Google stuff because the >> interface isn't available (though some of the C is >> in the manpages). But there is actually nothing that >> stops anyone from writing C (interface) >> documentation that would work more or less like the >> Elisp one. > > It would be an interesting project to convert those > documents to texinfo format. With Python it is > possible to convert the documentation (sphinx doc > generator) of Python and its libraries to texinfo, > and documentation can be gerated automatically for > any python project to texinfo. Yeah? What documents? You can get the Emacs manual in texinfo here: http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz I take it that's what you get with the info command, only not markuped, of course. In the the on-line help, the docstrings associated to defuns and variables, they aren't that advanced. The arguments should be mentioned, in caps - probably to make them visible - they get the `help-argument-name' face. In the source, it looks kind of strange with arguments not the same case in the docstring as everywhere else. But in help-mode the parameters in the definition gets uppercased, so there it's consistent. All parameters should be mentioned, in the docstring, and there should be two spaces after a full stop. This is something I learned from `checkdoc-current-buffer', check out this example - it should tell you arg2 isn't mentioned (apart from some other library related stuff that doesn't apply). But in reality far from everything is documented and sometimes it is, but not the parameters... (defun test-param-doc (arg1 arg2) "ARG1 does this. Also check out `find-file'." (interactive) nil) ; eval here (checkdoc-current-buffer t) ; and here Some hypertext is possible with `this' method - if there actually is such a function or whatever, that get hypertexted and the `button' face in help-mode. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-12 19:49 ` Emanuel Berg @ 2014-07-12 23:30 ` Javier 2014-07-13 16:52 ` Emanuel Berg 0 siblings, 1 reply; 31+ messages in thread From: Javier @ 2014-07-12 23:30 UTC (permalink / raw) To: help-gnu-emacs > Yeah? What documents? > > You can get the Emacs manual in texinfo here: > http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz I mean having in info format documents like this http://en.cppreference.com/w/Main_Page It's just an example, I just mean that there isn't that much documentation available in info format. Those documents could be converted to info, but html->info conversion is too problematic. Of course emacs/elisp are already documented in info format (as pretty much everything that is done by the FSF: bash, gcc, coreutils...) Emanuel Berg <embe8573@student.uu.se> wrote: > Javier <nospam@nospam.com> writes: > >>> Yes, documentation on-screen is great in the man >>> page sense, the online Emacs help sense, when you >>> want to know some part of the interface. If you do >>> Elisp for some time, and then switch to C, you feel >>> like an idiot having to Google stuff because the >>> interface isn't available (though some of the C is >>> in the manpages). But there is actually nothing that >>> stops anyone from writing C (interface) >>> documentation that would work more or less like the >>> Elisp one. >> >> It would be an interesting project to convert those >> documents to texinfo format. With Python it is >> possible to convert the documentation (sphinx doc >> generator) of Python and its libraries to texinfo, >> and documentation can be gerated automatically for >> any python project to texinfo. > > Yeah? What documents? > > You can get the Emacs manual in texinfo here: > > http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz > > I take it that's what you get with the info command, > only not markuped, of course. > > In the the on-line help, the docstrings associated to > defuns and variables, they aren't that advanced. > > The arguments should be mentioned, in caps - probably > to make them visible - they get the > `help-argument-name' face. In the source, it looks kind > of strange with arguments not the same case in the > docstring as everywhere else. But in help-mode the > parameters in the definition gets uppercased, so there > it's consistent. > > All parameters should be mentioned, in the docstring, > and there should be two spaces after a full stop. This > is something I learned from `checkdoc-current-buffer', > check out this example - it should tell you arg2 isn't > mentioned (apart from some other library related stuff > that doesn't apply). But in reality far from everything > is documented and sometimes it is, but not the > parameters... > > (defun test-param-doc (arg1 arg2) > "ARG1 does this. Also check out `find-file'." > (interactive) > nil) ; eval here > > (checkdoc-current-buffer t) ; and here > > Some hypertext is possible with `this' method - if > there actually is such a function or whatever, that get > hypertexted and the `button' face in help-mode. > ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-12 23:30 ` Javier @ 2014-07-13 16:52 ` Emanuel Berg 0 siblings, 0 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-13 16:52 UTC (permalink / raw) To: help-gnu-emacs Javier <nospam@nospam.com> writes: > I mean having in info format documents like this > > http://en.cppreference.com/w/Main_Page > > It's just an example, I just mean that there isn't > that much documentation available in info format. > Those documents could be converted to info, but > html->info conversion is too problematic. Aha, yes, that would be very helpful. I take it neither C or C++ changes a whole lot these days, and when they do (I'm sure) they are super-conscious not to break all the code in the wild (yes, a bit of a paradox: the new standard's main concern - be compatible with the old standard!) - so probably it is not worth the effort to translate on the fly, just something to have as a bunch of files on your computer would be sufficient. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-12 14:52 ` Javier 2014-07-12 19:49 ` Emanuel Berg @ 2014-07-13 1:40 ` Robert Thorpe 1 sibling, 0 replies; 31+ messages in thread From: Robert Thorpe @ 2014-07-13 1:40 UTC (permalink / raw) To: help-gnu-emacs Javier <nospam@nospam.com> writes: ... > It would be an interesting project to convert those documents to > texinfo format. With Python it is possible to convert the > documentation (sphinx doc generator) of Python and its libraries to > texinfo, and documentation can be gerated automatically for any > python project to texinfo. If you're using GNU C or C++ library functions and you have the manuals installed then C-h S will do the trick. I think the same is true for Fortran and Ada too. But, it would be very useful if more languages and libraries were supported. Automatic generation of info from other documentation formats would be very useful. It should be possible to add code to something like pandoc to output info files. BR, Robert Thorpe ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-01 4:41 Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS solidius4747 2014-07-01 7:44 ` James Freer [not found] ` <mailman.4638.1404200703.1147.help-gnu-emacs@gnu.org> @ 2014-07-07 23:12 ` Emanuel Berg 2014-07-08 8:37 ` solidius4747 2 siblings, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-07 23:12 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: > I wrote part 3: > http://tuhdo.github.io/emacs-tutor3.html > > It includes popular packages that people are > using. If you are new to Emacs, it would be useful. I wouldn't call that tutorial "mini"! It is clear you put a very big effort into this. You should get a medal, or some part of the gold stashed in IET, the International Emacs Treasury (if there is one). But, this makes me think, did you experience any shortcomings or "gaps" in the official Emacs manual? Perhaps you could integrate your project with it, somehow. If not, the official Emacs people should put a link to your project from the official site, at least, if they didn't already. Feedback on the material itself: the part on MELPA, what I can see it misses one essential part, namely how to *submit* code: both how that is done in practice, and guidelines on the Elisp itself (or references, if you don't feel like writing this all over). Keep it up! -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-07 23:12 ` Emanuel Berg @ 2014-07-08 8:37 ` solidius4747 2014-07-08 15:15 ` Emanuel Berg 0 siblings, 1 reply; 31+ messages in thread From: solidius4747 @ 2014-07-08 8:37 UTC (permalink / raw) To: help-gnu-emacs Vào 06:12:10 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết: > I wouldn't call that tutorial "mini"! It's mini relative to size of the official manuals. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 8:37 ` solidius4747 @ 2014-07-08 15:15 ` Emanuel Berg 2014-07-08 16:48 ` solidius4747 0 siblings, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-08 15:15 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: >> I wouldn't call that tutorial "mini"! > > It's mini relative to size of the official manuals. OK, again, I read an age-old one. That was perhaps 200 pages. Perhaps the more recent ones are huge. That would certainly reflect the scope. I'll get one, if I can... But the word "mini", you tend to think of something small. The Persian miniatures. A minibike. OK, a minibike is relative a normal bike. But it is still small :) Seriously, you wrote it, you name it - even Linus Torvalds is fine with distros calling it GNU/Linux. I guess he was just born that generous... ;) -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 15:15 ` Emanuel Berg @ 2014-07-08 16:48 ` solidius4747 2014-07-08 21:43 ` Emanuel Berg 0 siblings, 1 reply; 31+ messages in thread From: solidius4747 @ 2014-07-08 16:48 UTC (permalink / raw) To: help-gnu-emacs Vào 22:15:45 UTC+7 Thứ ba, ngày 08 tháng bảy năm 2014, Emanuel Berg đã viết: > solidius4747@gmail.com writes: > > > > >> I wouldn't call that tutorial "mini"! > > > > > > It's mini relative to size of the official manuals. > > > > OK, again, I read an age-old one. That was perhaps 200 > > pages. Perhaps the more recent ones are huge. That > > would certainly reflect the scope. I'll get one, if I > > can... > > > > But the word "mini", you tend to think of something > > small. The Persian miniatures. A minibike. OK, a > > minibike is relative a normal bike. But it is still > > small :) > > > > Seriously, you wrote it, you name it - even Linus > > Torvalds is fine with distros calling it GNU/Linux. I > > guess he was just born that generous... ;) > > > > -- > > underground experts united The current Elisp manual is over 1000 pages long: https://www.gnu.org/software/emacs/manual/pdf/elisp.pdf . Mine is over 100 pages long in PDF, so I think it's safe to call it mini. As for the Emacs Manual, it is currently over 600 pages long: http://www.gnu.org/software/emacs/manual/pdf/emacs.pdf . Mine is over 43 pages long. I also cover how to install and the issue with Capslock/Control, and how to swap the two to get a better Emacs experience (and other things that use Control in general). ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-08 16:48 ` solidius4747 @ 2014-07-08 21:43 ` Emanuel Berg 0 siblings, 0 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-08 21:43 UTC (permalink / raw) To: help-gnu-emacs solidius4747@gmail.com writes: > The current Elisp manual is over 1000 pages long: > https://www.gnu.org/software/emacs/manual/pdf/elisp.pdf > . Mine is over 100 pages long in PDF, so I think it's > safe to call it mini. Yeah, again, it is not a big issue, you call it what you want as you wrote it, it is just in my mind "mini" is something small. Kebnekaise is the highest mountain in Sweden (2,106 m). Compared to K2 (8,611 m) it isn't high at all. But I wouldn't call it a mini-mountain just the same. You know what I'm saying? PS. If the Danes had a mountain, it would have been high, too. DS. /The overground expert -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.5117.1404898261.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] <mailman.5117.1404898261.1147.help-gnu-emacs@gnu.org> @ 2014-07-09 16:55 ` Emanuel Berg 2014-07-11 11:51 ` Robert Thorpe 0 siblings, 1 reply; 31+ messages in thread From: Emanuel Berg @ 2014-07-09 16:55 UTC (permalink / raw) To: help-gnu-emacs Robert Thorpe <rt@robertthorpeconsulting.com> writes: > I recommend using a new version of the Emacs manual > set. The last version of Emacs 18 was released more > than 21 years ago. The current manual describes > RMAIL in detail. A separate manual describes GNUS, > that manual is part of the set. "Message-mode" is > the mode for composing email and newsgroup posts that > comes with GNUS. So message-mode comes with Gnus? I thought it was older than Gnus, pre-Internet, pre-everything, perhaps used with uucp or even for intra-computer "mails". It doesn't have the "gnus-" prefix that is very consistently implemented in the Gnus world. > It's used by GNUS, RMAIL and several other programs. > It's frequently used, I'm using it now, that's why > it's included in the manual set. Of-course reading > an old manual is still useful, many things haven't > changed. Yes. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS 2014-07-09 16:55 ` Emanuel Berg @ 2014-07-11 11:51 ` Robert Thorpe 0 siblings, 0 replies; 31+ messages in thread From: Robert Thorpe @ 2014-07-11 11:51 UTC (permalink / raw) To: Emanuel Berg; +Cc: help-gnu-emacs Emanuel Berg <embe8573@student.uu.se> writes: > Robert Thorpe <rt@robertthorpeconsulting.com> writes: > >> I recommend using a new version of the Emacs manual >> set. The last version of Emacs 18 was released more >> than 21 years ago. The current manual describes >> RMAIL in detail. A separate manual describes GNUS, >> that manual is part of the set. "Message-mode" is >> the mode for composing email and newsgroup posts that >> comes with GNUS. > > So message-mode comes with Gnus? I thought it was older > than Gnus, pre-Internet, pre-everything, perhaps used > with uucp or even for intra-computer "mails". It > doesn't have the "gnus-" prefix that is very > consistently implemented in the Gnus world. Message mode has nothing to do with pre-internet stuff. If you use GNUS then compose a message and key C-h m in the compose buffer. It'll say "Message mode defined in `message.el'". Open message.el and look at it's directory .../lisp/gnus/ . BR, Robert Thorpe ^ permalink raw reply [flat|nested] 31+ messages in thread
[parent not found: <mailman.5279.1405079523.1147.help-gnu-emacs@gnu.org>]
* Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS [not found] <mailman.5279.1405079523.1147.help-gnu-emacs@gnu.org> @ 2014-07-11 12:07 ` Emanuel Berg 0 siblings, 0 replies; 31+ messages in thread From: Emanuel Berg @ 2014-07-11 12:07 UTC (permalink / raw) To: help-gnu-emacs Robert Thorpe <rt@robertthorpeconsulting.com> writes: > Message mode has nothing to do with pre-internet > stuff. > > If you use GNUS then compose a message and key C-h m > in the compose buffer. It'll say "Message mode > defined in message.el'". Open message.el and look at > it's directory .../lisp/gnus/ . Strange, I remember "message" stuff from that old manual that didn't cover Gnus. But it could have been that it was mail-mode or something with Rmail and -message- in it, just not the mode. Was there a pre-Internet Emacs newsreader? Facts for fans: I heard there were two Gnus: Gnus, and then today's Gnus, ding ("Ding is not Gnus") - very funny (well), but anyway it didn't take so Gnus remained Gnus. -- underground experts united ^ permalink raw reply [flat|nested] 31+ messages in thread
end of thread, other threads:[~2014-08-25 14:05 UTC | newest] Thread overview: 31+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-07-01 4:41 Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS solidius4747 2014-07-01 7:44 ` James Freer [not found] ` <mailman.4638.1404200703.1147.help-gnu-emacs@gnu.org> 2014-07-01 14:16 ` Emanuel Berg 2014-07-01 14:38 ` James Freer [not found] ` <mailman.4649.1404225527.1147.help-gnu-emacs@gnu.org> 2014-07-08 8:36 ` solidius4747 2014-07-08 15:09 ` Emanuel Berg 2014-07-08 16:18 ` Drew Adams 2014-07-08 16:45 ` solidius4747 2014-07-08 21:36 ` Emanuel Berg 2014-07-09 2:41 ` solidius4747 2014-07-09 8:52 ` Robert Thorpe 2014-07-09 17:11 ` Emanuel Berg 2014-08-25 14:05 ` Jude DaShiell 2014-07-08 18:56 ` Robert Thorpe [not found] ` <mailman.5091.1404836351.1147.help-gnu-emacs@gnu.org> 2014-07-08 21:21 ` Emanuel Berg 2014-07-09 8:44 ` Robert Thorpe 2014-07-10 2:11 ` Bob Proulx [not found] ` <mailman.5163.1404958319.1147.help-gnu-emacs@gnu.org> 2014-07-10 22:16 ` Emanuel Berg 2014-07-12 14:52 ` Javier 2014-07-12 19:49 ` Emanuel Berg 2014-07-12 23:30 ` Javier 2014-07-13 16:52 ` Emanuel Berg 2014-07-13 1:40 ` Robert Thorpe 2014-07-07 23:12 ` Emanuel Berg 2014-07-08 8:37 ` solidius4747 2014-07-08 15:15 ` Emanuel Berg 2014-07-08 16:48 ` solidius4747 2014-07-08 21:43 ` Emanuel Berg [not found] <mailman.5117.1404898261.1147.help-gnu-emacs@gnu.org> 2014-07-09 16:55 ` Emanuel Berg 2014-07-11 11:51 ` Robert Thorpe [not found] <mailman.5279.1405079523.1147.help-gnu-emacs@gnu.org> 2014-07-11 12:07 ` Emanuel Berg
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).