Re: How to document for html and Word -- don't imitate MS's goofs

From: r coyne (duckingsnofair@yahoo.com)
Date: Sat Feb 01 2003 - 18:46:17 EST

  • Next message: Jeremiah Foster: "Re: How to document for html and Word -- don't imitate MS's goofs"

    Jeremiah,

    Thanks for anything you care to do, and since I don't
    really use abiword that much maybe I don't count for
    much, but I do have some advice, a caution. The way
    you are proposing to do your how-tos, you are
    following MS in a couple of blunders they make in
    Windows that really annoy and discomfit me.

    First, your "documentation" essentially consists
    entirely of menu trees, i.e., where to find the
    command. But the whole point of menus and windowing
    shells generally is supposed to be to eliminate or
    greatly reduce the need for that sort of thing. The
    tree structure is supposed to be intuitive enough that
    the user needn't remember or look up a whole bunch of
    these routes/commands. If it's not, then we are back
    to the command-line-era problem of having to memorize
    a slew of commands, except that now each one is
    numerous stages, a whole menu path instead of a single
    word and maybe a bit of optional syntax. Your how-to
    collection will amount to a Command Reference Manual,
    only four times as long and more scattered. If this
    is indeed a great need, then the greater need, the
    best remedy, is for the developers to make it less so.
     This indeed is, I believe, *the* great problem with
    Windows nowadays, the main reason people are
    bewildered and upset by computers. But since the
    problem does very much exist and is hard to correct,
    especially in a program like abiword that has a niche
    as a Word clone, I don't mean to discourage you from
    writing the how-tos and including this stuff; my
    suggestion is that you need to include *other*
    information as well.

    Which brings us to MS's (and abiword's) second
    blunder: The SaveAs dialog is unclear and rather
    frightening because it confuses and conflates two
    totally separate ideas/issues, namely file *type*,
    i.e., format, and filename *extension*. What I want
    to know is, What will this thing *do* if I click it.
    With "save as Word doc" I can sort of guess, because I
    know that Word and abi each have a whole bunch of
    internal formatting codes that are not the same, and
    presumably what I get is a file that uses the Word
    codes to correspond to and thus produce in Word a
    document that looks more or less the same as the abi
    one. But what does it *mean* to "save as HTML"? An
    HTML document/file simply *is* text. So will Save As
    HTML simply strip out all the abw complexities to
    produce straight, old-fashioned text and then tack
    ".html" on the end of my specified filename? Or will
    it try to translate the abi formatting codes into HTML
    formatting tags so as to make it look alike in a
    browser, as for the Word case? But that's only
    layout; what about links? Will anything that looks
    like an Internet address be duplicated (and expanded
    into a full URL) in a HTML tag to make it function as
    an active link in the HTML document? That's the sort
    of thing Yahoo news does, and it's often stupidly
    inappropriate and annoying; does abi do it better?
    And if there are images and frames and the like in the
    abi document, the sorts of things that HTML does by
    referring to separate files, will such files be
    generated? Where will they be put and what will they
    be called?

    Obviously a how-to intended largely for beginners will
    not give all the details; that's what the full
    documentation is for. Since you're writing it, you'll
    have to use your judgment, and I won't complain. But
    you should tell us *something*, enough to give me a
    basic, sketchy understanding of what's about to
    happen, so that I can figure out whether it's what I
    want and whether it's safe and what I'll need to do
    later. Without that much, I am left feeling I don't
    dare click anything, because who knows what it might
    do to me? And -- especially since you do offer this
    in hypertext format -- you should include a full set
    of references/links to the complete documentation, for
    those who want more info. HTML isn't about fancy
    looks, it's about hypertext links, so use it for what
    it's good for.

    --- Jeremiah Foster <jeremiannika@attbi.com> wrote:
    > Greetings,
    >
    > I love AbiWord. I would like to contribute by
    > producing "How tos" for
    > the community at large. I think there is a growing
    > linux desktop
    > userbase who is less familiar with computers and
    > editors. I feel to
    > strengthen adoption of one of the best editors
    > anywhere, AbiWord ought
    > to provide basic, clearly written How tos. I have
    > included a sample of
    > the How to that I think may prove useful. I welcome
    > comment and
    > suggestions and hope that it may be considered
    > useful.
    >
    > The document is presented unformatted inline and as
    > html in an
    > attachment.
    >
    > Jeremiah
    >
    >
    > How to save AbiWord documents in
    >
    > HTML or Word.
    >
    >
    > Purpose: This document aims to explain how to save
    > documents in AbiWord
    > as html or Microsoft's Word format.
    >
    >
    > Summary: Go to "File -> Save As -> Save file as
    > type -> html (.html,
    > .htm)"
    >
    > Go to "File -> Save As -> Save file as type ->
    > Word (.doc)"
    >
    >
    > Contents: If you can open or create a document in
    > AbiWord, you can save
    > it as Hypertext Markup Language (HTML) or a Word
    > document. This is
    > useful if you are going to share this document on a
    > web site or with
    > someone who uses Microsoft's Word software to view
    > and edit documents.
    >
    >
    > To do this go to the "File" menu in the upper left
    > corner of the AbiWord
    > top tool-bar and click on "Save As ..." (This will
    > be referredas "File
    > -> Save As" throughout this document.) There is
    > also an icon provided
    > for this action; AbiWord Image write.disk.png
    >
    >
    > A dialog box pops up, prompting you to pick a
    > format for the document.
    > There is a left-hand box that says; "Save as type:"
    > You can pull down
    > the dialog box just to the right of this and chose a
    > format.
    >
    >
    > * For HTML - HTML 4.0 (.html .htm) should
    > be selected.
    > * For Word - Microsoft Word (.doc) should
    > be selected.
    >
    > You can see that the format is named and the
    > ensuing document suffix is
    > displayed. If you were to save a document and call
    > it MyPage, when you
    > save it as HTML it will be called MyPage.html.
    > Similarly, it would be
    > called MyPage.doc if you saved it in Word format.
    >
    >
    >
    > Additional Notes: Microsoft Word is a proprietary
    > format. This means
    > that it is copyrighted by Microsoft and can be
    > changed by them without
    > public comment. Documents can also be displayed in
    > XHTML 1.0 (.xhtml)
    > format as well. This is perhaps preferred since it
    > is the transitional
    > markup language which allows for both XML syntax and
    > backwards
    > compatibility.
    >
    >
    >
    ---------------------------------
    /home/jeremiah/documents/linux_documents/AbiWord/How_to_save.htmlbody{
    font-family: "Times New Roman"; font-variant: normal;
    text-indent: 0in; widows: 2; font-style: normal;
    font-weight: normal; text-decoration: none; color:
    #000000; text-align: left; font-size: 12pt;
    font-stretch: normal; background-color:
    #ffffff;}@media print{ body { padding-top: 1in;
    padding-bottom: 1in; padding-left: 1in;
    padding-right: 1in; }}p, .Normal{ font-family: "Times
    New Roman"; margin-top: 0pt; font-variant: normal;
    margin-left: 0pt; text-indent: 0in; widows: 2;
    font-style: normal; font-weight: normal;
    text-decoration: none; color: #000000; text-align:
    left; margin-bottom: 0pt; margin-right: 0pt;
    font-size: 12pt; font-stretch: normal;}
    How to save AbiWord documents in

    HTML or Word.

    Purpose: This document aims to explain how to save
    documents in AbiWord as html or Microsoft's Word
    format.

    Summary: Go to "File -> Save As -> Save file as type
    -> html (.html, .htm)"

             Go to "File -> Save As -> Save file as type -> Word
    (.doc)"

    Contents: If you can open or create a document in
    AbiWord, you can save it as Hypertext Markup Language
    (HTML) or a Word document. This is useful if you are
    going to share this document on a web site or with
    someone who uses Microsoft's Word software to view and
    edit documents.

            To do this go to the "File" menu in the upper left
    corner of the AbiWord top tool-bar and click on "Save
    As ..." (This will be referredas "File -> Save As"
    throughout this document.) There is also an icon
    provided for this action;

     A dialog box pops up, prompting you to pick a format
    for the document. There is a left-hand box that says;
    "Save as type:" You can pull down the dialog box just
    to the right of this and chose a format.

        For HTML - HTML 4.0 (.html .htm) should be
    selected.
        For Word - Microsoft Word (.doc) should be
    selected.

     You can see that the format is named and the ensuing
    document suffix is displayed. If you were to save a
    document and call it MyPage, when you save it as HTML
    it will be called MyPage.html. Similarly, it would be
    called MyPage.doc if you saved it in Word format.

            

    Additional Notes: Microsoft Word is a proprietary
    format. This means that it is copyrighted by Microsoft
    and can be changed by them without public comment.
    Documents can also be displayed in XHTML 1.0 (.xhtml)
    format as well. This is perhaps preferred since it is
    the transitional markup language which allows for both
    XML syntax and backwards compatibility.

    __________________________________________________
    Do you Yahoo!?
    Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
    http://mailplus.yahoo.com
    -----------------------------------------------
    To unsubscribe from this list, send a message to
    abiword-user-request@abisource.com with the word
    unsubscribe in the message body.



    This archive was generated by hypermail 2.1.4 : Sat Feb 01 2003 - 18:49:18 EST