Steve Youngs writes:
> * Johann G Oskarsson <johann@xxxxxxxxxxxxxx> writes:
>
> > Steve Youngs writes:
> >> * Johann Gunnar Oskarsson <johann@xxxxxxxxxxxxxx> writes:
>
> >> > Info is ugly.
> >>
> >> I agree. But it is infinitely better than having to fire up some
> >> bloated fucking web browser just to read plain text.
>
> > Well, I've always aimed at a DSO or something for internal reading.
>
> Why not just fix/enhance the Emacs/W3 package?
Becouse it's terribly b0rken and slow.
> >> > Info does not adapt well to variable width screens. This is mostly
> >> > the reason why I want something that's more dynamically rendered.
> >>
> >> OK, but surely the SXEmacs info parser/reader/whatever could easily be
> >> made to handle this?
>
> > Possibly, but it'll still be more ugly than text rendered html.
>
> Bullshit! Plain text is plain text. It's not supposed to look pretty
> it is supposed to look like fucking text!!
Do you realize I've used emacs-w3m on an fscking tty exclusively for
*months*, I think half a year is not out of the question!? (If not
more).
No, let's attach some more ! and ? to this !!!!!!!!!!!!!!!!!! ??????
> >> Yes! SXEmacs can display pictures, so info files under SXEmacs should
> >> display pictures too.
>
> > Or the alternative format... :P
>
> No. Info.
>
> If you want html, do `makeinfo --html ...'.
Do you realize what you're saying? Here I have been talking about
using the fscking meta tags to do the same kind of navigation control
info provides, and here you go about the fscking ugly makinfo
generated html again!
> >> > When it comes to the dir files .... it annoys me a lot that I can't
> >> > choose between 2 different versions of installed info files, I'll
> >> > always be reading the one that's first in the info path, no matter
> >> > where it's added to the actual "dir".
> >>
> >> C-u C-h i /path/to/the/file_you_really_want RET
>
> > K, but there should be a better way.
>
> I doubt it.
No, it *should*!
> >> But I agree, if the terminal can handle it, info should display it.
>
> > Then we'd need to patch info/replace it to allow such formatting.
> > Terminals can display underline and italics (at least the ANSI
> > standard has escape sequences for it).
>
> Yes.
>
> >> > Please note that I like to write docs, and I want some control of the
> >> > layout, both on graphical and text displays, and I'm not getting that
> >> > control with info.
>
> >> You are not getting _enough_ control.
>
> > No, I'm not.
>
> And I'm also willing to bet that you already have more control than
> you think you do.
I may, but now scroll up and read the bit about using tty for months,
then read it again.
When you get to this bit, stare at it for a while.
> >> > In other words, I'd like something like <strong> and <em> in
> >> > on-line docs.
>
> >> Have we switched from discussing Texinfo manuals to lisp source doc
> >> strings now? If we are, eval this in scratch...
>
> > But I want the *same* stuff of formatting for the doc strings as
> > manuals.
>
> I'm not sure that I do. And I'm definitely not convinced of the
> merits of such and endeavour.
Read on.
> > I want it to feel pretty much the same, when reading docs.
>
> Which is why plain text is so good. It gives you the same look and
> feel in a doc string as it does in a manual.
Will you forget about pain text already!!!!!
> >> (defvar test-var nil
> >> "this is `emphasised' in the doc string.")
>
> >> then do C-h a test-var RET, then RET on the var name in the Hyper
> >> Apropos buffer, look at the doc string.
>
> > Yes, this is an emphasiation I'm aware of, but there's only one of
> > it. I want something that will link me to the <insert some
> > replacement of info> page with more info.
>
> Yes this would be good. And, BTW, this is something that is also half
> present already. Eval this...
>
> (defvar test-var nil
> "click this `emacs-version', whee!")
>
> ...and look at `C-h v test-var RET'
>
> I'd like to be able to do something like...
>
> (defvar test-var nil
> "A variable.
>
> See `REF: (gnus)Posting Styles' for more info.")
>
> But even this is simply an extension to what we already have. No need
> for wheel inventing here.
Well, here we are, talking about a wheel with 20 meter spikes on, and
you want to *keep* it!
> >> I know that this is a _very_ cruddy way of doing it and it doesn't
> >> work if your just do C-h v, but what I am getting at is that
> >> emphasising text in lisp source doc strings is almost there
> >> already.
>
> > Almost doesn't feel good enough ;)
>
> But "almost" means the work is 90% done already.
Yady yady yady (or whatever kids use when they don't want to listen).
> > [...]
> >> > The rest of the world has moved to html or other xmls for
> >> > on-line docs, why do we stay in the dark ages? Becouse of
> >> > rmsism?
> >>
> >> No. Because the rest of the world is stupid. The best way to
> >> render plain text is with plain text. If our docs and manuals are
> >> in HTML only, or even primarily in HTML, sooner or later (and I'm
> >> betting a lot sooner than later) we'll get complaints from people
> >> saying they can't read our docs in their
> >> latest-flavour-of-the-month web browser.
>
> > Who sais they have to advertised as html files? I mean, kde and gnome
> > are probably using html, but with their own browsers
>
> Probably. And the last time I used the GNOME help browser, I hated
> it. Compared to viewing an info file is so fucking slow!!
Do you really think I'd make doc viewing slow? !!!!!!!
I'm useing a playstation gnu fscking rms it!
> Oh, and another nitpick... there is no such word as "sais", it is
> "says". :-P
Whatever!
> >> Now, please understand this, I _do not_ have any problems with us
> >> distributing HTML docs. I _do_ have a problem with distributing _only_
> >> HTML docs, or even making HTML docs the primary medium.
>
> > K, as a compromize I'll be working on an html renderer module (or
> > something) that'll provide the same type of navigation as info. The
> > texinfo files must then be transformed correctly, which'll be quite
> > different from current texi-->html converters.
> NO!!! If you can't make it work from `makeinfo --html', then don't
> even bother.
> The more I think about this whole reinventing of the doc system
> bullshit, the more I hate it!
That's just becouse....
> > Also, as I've said before, I want an inclusion mechanism of doc
> > strings into the texinfo stuff. This will possibly not be so much a
> > trouble for the lisp strings, but we *must* completely change the
> > system for C doc strings.
>
> Forget it! (read: you are scaring the fuck out of me)
...you're scared.
Now, as is in my mail to xemacs-patches, and probably -beta or -design,
the current doc system has way, way, *waaaaaayyyyy* to much
redundancy!
If it weren't for this redundancy, I probably wouldn't (want to) work
so hard on this, but this is a maintainance nightmare.
K, there is the doc string, ok, that's good. Then there is the *same
text* in the info manual, yanked, not modified. It's just sitting
there. And guess who get's updated when the need comes?
This is not *just* becouse I want fancy rendering of the fscking docs,
it's becouse I want to eliminate this redundancy.
There is mostly no fscking need to have the api (read: doc strings)
in most of the manuals. In fact there is a need for only one, an api
reference which can be an appendix to the lispref.
I mean, *read* the fscking manual (here, I'm thinking of the ECB,
EmacsCodeBrowser user manual) ... page after page of api, and what the
heck am I going to do with this info as a user? (OK, me personally,
but I don't want to read it *now* and think of the customize users.)
I want this crud out of the manuals and into a reference!
Good manuals are *not just* documenting 97% of the software, they're
also good to read.
Just out of curiousity, I'm reading the XEmacs user manual now
C-h i d m XE TAB RET
And, as I thought, mostly crud.
Why do we have a GNU Manifesto since 1823 in our docs?
Can we please agree that the docs need a bit of a touchup/rewrite?
A change of doc system is a nice way to actually accomplish this.
Have fun,
Johann
P.S. I'm mostly just tired of thinking about this stuff, so I'm just
ending this email.
|