From mboxrd@z Thu Jan 1 00:00:00 1970 From: Izzie Subject: Re: orgmode manual improvement suggestion. Date: Tue, 5 Apr 2011 08:42:36 +0000 (UTC) Message-ID: References: <3857.1301957233@alphaville.usa.hp.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=51249 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q71qh-00030l-56 for emacs-orgmode@gnu.org; Tue, 05 Apr 2011 04:42:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Q71qf-0001We-LG for emacs-orgmode@gnu.org; Tue, 05 Apr 2011 04:42:55 -0400 Received: from lo.gmane.org ([80.91.229.12]:50754) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Q71qf-0001WS-7Y for emacs-orgmode@gnu.org; Tue, 05 Apr 2011 04:42:53 -0400 Received: from list by lo.gmane.org with local (Exim 4.69) (envelope-from ) id 1Q71qd-0007kQ-FZ for emacs-orgmode@gnu.org; Tue, 05 Apr 2011 10:42:51 +0200 Received: from vol21-3-82-244-47-150.fbx.proxad.net ([82.244.47.150]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Tue, 05 Apr 2011 10:42:51 +0200 Received: from ml_orgmode.kapush by vol21-3-82-244-47-150.fbx.proxad.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Tue, 05 Apr 2011 10:42:51 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Nick Dokos hp.com> writes: > If you download an org distribution (through git or a tar file or what > have you), you should be able to find the doc/org.texi file which is > used to generate the manual. Found it. In debian it's gzipped and located in /usr/share/doc/org-mode/ where I found both org.texi.gz and orgguide.texi.gz I was hoping org mode documentation had been made with org mode, I wasn't expecting a texi file format I had not been introduced to yet. I can use it to generate the manual, but I can't jump into modifying the source. > The following page > > http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Output- Formats.html#Output-Formats > > describes briefly how to produce each output format from the texi file. Thanks. how come this is not part of the manual ? It is a good practice to provide information about where to find the manual and how to produce a specific format (especially when not providing it). > > And that the single page version of "the compact Org-mode Guide" is > > missing. > > But I don't know whether the single page document ever was (or should > be) available from the orgmode site, so I'm not sure I'd characterize is > as "missing": Matt and/or Jason would know better. It's actually available as a pdf download but this is not what I expected (a single html page) so I deemed it "missing". I usually expect to find both single page html and one page per section html versions along with gzipped versions (for those who want to download it). IMHO the current "Documentation" section found at http://orgmode.org/ could use a quick rewrite. It might be related to english not being my native language but when I read "read the online manual" I understand that there is a different offline version. Rewritten to "read the manual online" this potential confusion is no more (at least for me). There's also a lack of consistency, for the guide it says: * Read the online compact guide or download it as a PDF document. (...) while for the manual the same info is broken into two different sections: * Read the online manual. (...) * Download the manual as a 200-page PDF document. Starting the entries with "Read", "Download", "Buy" helps scanning through the section by providing info right away, out of luck the specific version i was looking for is the one which doesn't follow this pattern: * You can also have the entire manual in a single monolithic file. I had the online manual open which offers no easily found way to get to the place where other versions of the manual can be found, so I headed for the orgmode website, scanned the documentation section and missed the single html page version I was looking for, because it breaks the pattern. As I am expecting this version to be found I read the whole section from the beginning and missed it again, for some reason "single monolithic page" didn't fire up my brain looking for a "single html page", At this point I still assume the single html page version exists and can be found in this section so I started again from the top and clicked each link one after the other until I finally found it. Leading to this improvement suggestion thread.