* orgmode manual improvement suggestion.
@ 2011-04-04 21:58 Izzie
2011-04-04 22:47 ` Nick Dokos
0 siblings, 1 reply; 4+ messages in thread
From: Izzie @ 2011-04-04 21:58 UTC (permalink / raw
To: emacs-orgmode
Reading the manual, I found myself needing a single page version which
I found after a quick search, I noticed that org mode manual is
offered in several formats but not as much as emacs'[1]., which made
me wonder if there is a org manual plain text version that can be
downloaded somewhere.
I also want to report noticed a broken link, the first link in this
section [2] to "this directory" leads to a 404.
And that the single page version of "the compact Org-mode Guide" is
missing.
Iz.
[1] http://www.gnu.org/software/emacs/manual/emacs.html
[2] http://orgmode.org/index.html#sec-4_1
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: orgmode manual improvement suggestion.
2011-04-04 21:58 orgmode manual improvement suggestion Izzie
@ 2011-04-04 22:47 ` Nick Dokos
2011-04-05 8:42 ` Izzie
0 siblings, 1 reply; 4+ messages in thread
From: Nick Dokos @ 2011-04-04 22:47 UTC (permalink / raw
To: Izzie; +Cc: nicholas.dokos, emacs-orgmode
[forgot to cc: the list]
Izzie <ml_orgmode.kapush@antichef.net> wrote:
> Reading the manual, I found myself needing a single page version which
> I found after a quick search, I noticed that org mode manual is
> offered in several formats but not as much as emacs'[1]., which made
> me wonder if there is a org manual plain text version that can be
> downloaded somewhere.
>
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.
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.
> I also want to report noticed a broken link, the first link in this
> section [2] to "this directory" leads to a 404.
>
Somebody reported that a few days ago: I guess it has not been fixed
yet.
> And that the single page version of "the compact Org-mode Guide" is
> missing.
>
Follow the link called "Generating HTML" in the above page to find
out how to generate HTML output in a single page (the input file
is doc/orgguide.texi).
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.
Nick
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: orgmode manual improvement suggestion.
2011-04-04 22:47 ` Nick Dokos
@ 2011-04-05 8:42 ` Izzie
2011-04-05 16:35 ` Nick Dokos
0 siblings, 1 reply; 4+ messages in thread
From: Izzie @ 2011-04-05 8:42 UTC (permalink / raw
To: emacs-orgmode
Nick Dokos <nicholas.dokos <at> 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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Re: orgmode manual improvement suggestion.
2011-04-05 8:42 ` Izzie
@ 2011-04-05 16:35 ` Nick Dokos
0 siblings, 0 replies; 4+ messages in thread
From: Nick Dokos @ 2011-04-05 16:35 UTC (permalink / raw
To: Izzie; +Cc: nicholas.dokos, emacs-orgmode
[Noch ein mal: I forgot to copy the list. Apologies... to Izzie in
particular who is receiving multiple instances. At least, I edited
this version down a bit.]
Izzie <ml_orgmode.kapush@antichef.net> wrote:
> ...
> 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.
>
Texinfo format predates org by 20 years or so and is the GNU software
standard for documentation. Since org is GNU software, it has to conform
to the standard. It might be possible to do a texinfo exporter but a)
nobody has done that (yet) and b) it would be a lot of effort to rewrite
the documentation in org.
>
> 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).
>
*Which* manual? It *is* part of the texinfo manual. If you are saying why
is it not part of the org manual, why should it be? It has nothing to do
with org.
A link in the Documentation section of org might be warranted however:
``Org mode manuals are written in texinfo and they are part of the
distribution: doc/org.texi and doc/orgguide.texi, although depending
on how you get org, they may be in one of many different places. If
you want to produce documentation in different formats, please
see <a href="http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Output-Formats.html#Output-Formats">here</a>.''
> > > 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.
>
These sound like reasonable questiions/suggestions to me and I'm sure
the webmasters will consider them carefully (just don't expect immediate
gratification: they all do it in their spare time.)
Nick
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2011-04-05 16:36 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-04-04 21:58 orgmode manual improvement suggestion Izzie
2011-04-04 22:47 ` Nick Dokos
2011-04-05 8:42 ` Izzie
2011-04-05 16:35 ` Nick Dokos
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.