<?xml version='1.0' encoding='iso-8859-1' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                      "docbook/dtd/xml/4.2/docbookx.dtd" [
  <!ENTITY % fnc SYSTEM "fnc.ent">
  <!ENTITY % var SYSTEM "var.ent">

  %fnc;   <!-- LysKOM functions -->
  %var;   <!-- LysKOM variables -->

  <!ENTITY editcmd.ent SYSTEM "editcmd.ent">
]>

<book lang="en">
  <chapter id="chapter:texts">
    <title>Texts in LysKOM</title>

    <para>
      Texts are the heart of LysKOM. The whole point of the system is
      to write and read texts. Every text in LysKOM has a few
      important properties: there are always one or more recipient(s),
      there is an author, a subject line and text body (technically,
      the subject line is part of the text body).
    </para>


    <section id="texts:recipients">
      <title>Recipients</title>

      <para>
        Every text has one or more recipients (it is possible to
        create a text with no recipients, but generally not a very
        good idea since only the author is able to read them and the
        server may delete them at any time). The recipient list
        determines which conferences the text appears in. The text
        will be presented to members of those conferences as they use
        LysKOM. Note that users who are not members of the recipients
        may also be able to read the text, if at least one of the
        recipients is an open conference.
      </para>

      <para>
        There are three kinds of recipients: regular recipients,
        carbon copy (cc) recipients (known as "extra-kopiemottagare"
        in Swedish) and blind carbon copy (bcc) recipients (known as
        "dold kopia" in Swedish).
      </para>

      <formalpara>
        <title>Regular recipients</title>
        <para>
          Regular recipients are the normal case. When a text is
          commented, the regular recipients of the commented text will
          be copied to the comment.
        </para>
      </formalpara>

      <formalpara>
        <title>Carbon copy recipients</title>

        <para>
          Carbon copy recipients are used when a single text, but not
          its comments, are relevant to the topic of a conference. For
          example, marker conferences ("adderingsmöten" in Swedish),
          should be made carbon copy recipients, not regular
          recipients, so that future comments do not appear in the
          marker conferences. Carbon copy recipients are also useful
          if you want to notify the members of a conference, or a
          particular user, about the existence of the text.
        </para>
      </formalpara>

      <formalpara>
        <title>Blind Carbon Copy Recipients</title>

        <para>
          Blind carbon copy recipients are invisible recipients. Only
          those who have access to the recipient conference will even
          know that a BCC recipient exists. BCC recipients are useful
          when you want to copy a message to a closed conference
          without anyone else knowing.
        </para>
      </formalpara>
    </section>

    <section id="texts:comments">
      <title>Comments and Footnotes</title>

      <para>
        A text may be a comment to another text, and may have one or
        more comments (in fact, <emphasis>most</emphasis> texts are
        comments to something else). A text without any comments at
        all is referred to as a <firstterm>root</firstterm>. All the
        comments that can be reached from a text by reading comments
        and comments-to-comments (and so on) are collectively known as
        a <firstterm>comment tree</firstterm>. The text a comment is a
        comment to is known as the <firstterm>commented</firstterm>
        text.
      </para>

      <para>
        A footnote is a special kind of comment. Only the author of a
        text can add a footnote to it. In the elisp client, footnotes
        are shown before any other comments; in other clients,
        footnotes are shown together with the original texts.
        Typically, footnotes are used when the author wants to correct
        or add to the information in an existing text.
      </para>

      <para>
        Anyone can write a comment to any text they can read, and the
        comment can have any recipients (they are usually the same as
        the recipients of the commented text, but not always). It is
        possible for the author of a text to request that nobody write
        a comment to it, but such a request does not
        <emphasis>prevent</emphasis> comments.
      </para>

      <para>
        A comment whose recipients are the author of the commented
        text and the author of the comment is referred to as a
        <firstterm>personal comment</firstterm> or <firstterm>private
        reply</firstterm>.
      </para>

      <para>
        When writing a comment, check that the recipients suggested by
        the client are appropriate. In general, peoples mailboxes are
        always appropriate, but if the topic of the discussion strays,
        one or more of the open conferences may no longer be
        appropriate. Sometimes the client will ask if you want to add
        the author of the commented text as a recipient to a comment
        you write. This happens when the author of the commented text
        is not a member of any of the recipients. In general, it is
        appropriate to answer "yes" to this question.
      </para>

      <para>
        From time to time you may find that entire comment trees are
        being sent to your mailbox. This often happens when someone
        writes a comment to one of your texts in a conference that you
        are not a member of. If you are not interested in the
        discussion, remove your mailbox using one of the commands for
        manipulating recipients <xref
        linkend="texts:manip:recipients"/>. You may also consider
        joining the conference in question if you are participating in
        the discussion.
      </para>

      <para>
        If discussions keep ending up in your mailbox because you tend
        to participate in discussions that are in conferences you are
        not a member of, you can request that comments be sent to an
        alternate conference instead by using the
        &fn:kom-redirect-comments; command. Not all clients obey this
        instruction, but more and more do.
      </para>
    </section>



    <section id="texts:writing">
      <title>Writing texts</title>

      <para>
        To write a new text, use &fn:kom-write-text;. To write a new
        comment, use &fn:kom-write-comment;. To write a new footnote,
        use &fn:kom-write-footnote;. There are also a few specialized
        commands for writing texts such as &fn:kom-private-answer; for
        writing a private reply to a text; and
        &fn:kom-comment-previous; and &fn:kom-private-answer-previous;
        for writing a comment (or private reply) to the next-to-last
        text (useful when you read a text and a comment to that text,
        and decide you also want to write a comment). See the command
        reference for more.
      </para>

      <para>
        When you issue a command to write a text, you will be
        presented with an <firstterm>edit buffer</firstterm>. This is
        the Emacs buffer in which you compose your text. The edit
        buffer is divided into two sections: the header and the body.
        These sections are separated with a dashed line. Within the
        header, the TAB and M-TAB keys move the cursor between
        "interesting" positions; the M-TAB key works in the text body
        as well, but the TAB key does not (it just inserts a tab, as
        you would expect).
      </para>

      <para>
        You can edit any header line by hand, but you may not get the
        results you expect, so be careful. If you are unsure, use the
        commands that manipulate the header instead. Before the
        subject line, there is a field labeled "Add". Right-click this
        to bring up a menu of headers to add.
      </para>

      <para>
        Editing works just like in Emacs. In fact, the major mode of
        the edit buffer is text-mode, so if you're used to editing
        text files with Emacs, everything should be familiar. The
        LysKOM menu (in the menu bar) contains all LysKOM-specific
        commands available in this buffer.
      </para>

      &editcmd.ent;
    </section>


    <section>
      <title>Manipulating existing texts</title>

      <para>
        You can't change a text in LysKOM once it's been sent. Even
        the administrator can't. You can, however, change the
        recipients, the comment links and features like requesting no
        comments or read confirmation at any time.
      </para>

      <section id="texts:manip:deleting">
        <title>Deleting texts</title>

        <para>
          It is possible to delete texts, but you really shouldn't do
          it. In particular you should never delete a text that has a
          comment. If you do, that comment will no longer be a comment
          to anything, and making sense of it might be impossible once
          your text is gone. This annoys not only the person who wrote
          the comment, but also the people who read it afterwards. If
          you need to make a correction or retraction to a text, write
          a footnote to it instead.
        </para>

        <para>
          If you really feel you have to delete a text, there is a
          command for it, and it's in the command reference.
        </para>
      </section>

      <section id="texts:manip:comments">
        <title>Manipulating comments</title>

        <para>
          The comment links between texts can be changed after the
          fact. To make an existing text a comment to another existing
          text, use &fn:kom-add-comment;. To remove a comment from an
          existing text, use &fn:kom-sub-comment;.
        </para>
      </section>

      <section id="texts:manip:recipients">
        <title>Manipulating recipients</title>

        <para>
          The initial list of recipients is determined when a text is
          created, but recipients can be added, removed, or converted
          at any time after that. Use &fn:kom-add-recipient; to add a
          recipient or convert an existing recipient to a new type
          (e.g. from regular to carbon copy or vice versa). Use
          &fn:kom-sub-recipient; to remove an existing recipient. Note
          that only the person who added a recipient in the first
          place, or the supervisor of the recipient, may remove a
          recipient from a text.
        </para>

        <para>
          The command &fn:kom-move-text; is helpful when moving a text
          from one conference to another, and &fn:kom-move-text-tree; is
          useful when moving a text and all its comments.
        </para>
      </section>
    </section>




    <section id="texts:special">
      <title>Special Texts</title>

      <section id="texts:presentations">
        <title>Presentations</title>

        <para>
          Every conference and person can and should have a
          presentation. A conference presentation should contain
          information about the conference, such as what topics are
          appropriate, related conferences and possibly external
          links. Do not confuse presentations with FAQs; there is
          support for FAQ texts as well (<xref linkend="texts:faqs"
          />).
        </para>

        <para>
          Keeping with the tradition of openness, presentations of
          persons in most LysKOM systems are fairly detailed, almost
          always including the real name and location of the person,
          and frequently including telephone number, address,
          interests, job details and more. Check what the tradition is
          in your system by looking at the presentations of some of
          the regulars.
        </para>

        <para>
          You can see the presentation for any conference or person
          using &fn:kom-review-presentation;. To change or create a
          presentation for a person or conference, use
          &fn:kom-change-presentation;. You can remove a presentation
          using &fn:kom-remove-presentation;. To make an existing text
          the presentation of a conference, use
          &fn:kom-set-presentation;.
        </para>

        <para>
          When you use &fn:kom-change-presentation; to create the
          presentation for a conference or person, the recipient of
          that text will be a special conference (there is one for
          conferences and one for persons). If the conference is
          secret, the recipient will be the conference itself since
          there is no point in presenting a secret conference.
        </para>

        <para>
          When you use &fn:kom-change-presentation; to change a
          presentation the new presentation will be a comment to the
          old one. This is a convention that helps people see what
          differs from one presentation to the next.
        </para>

        <para>
          Presentations are protected from automatic deletion, but can
          be deleted manually. Don't do that.
        </para>

        <para>
          By default, the names of users without presentations are
          displayed with a line through the name. You can change this
          by altering the value of &var:kom-highlight-conferences;.
        </para>
      </section>

      <section id="texts:notices">
        <title>Notices</title>

        <para>
          A notice is a text containing important information about
          the server, a person or a conference. Each object can have
          at most one notice. Notices are sent to a special
          conference. Check the recipient of your notice if it is
          applied to a secret conference; the conference will be less
          secret if its notice is in a public conference.
        </para>

        <para>
          Notices are protected from automatic deletion but can be
          deleted manually. Don't do that. If you want to remove a
          notice, use the appropriate command (see below).
        </para>

        <simplesect id="texts:notices:server">
          <title>Server notices</title>

          <para>
            The server notice (sometimes called "message of the day")
            is shown on login and can be reviewed by using the
            &fn:kom-status-server;; the text number of the server
            notice will be listed.
          </para>

          <para>
            The server notice is set using the &fn:kom-set-motd; and
            removed with &fn:kom-remove-motd; These commands are only
            available in administrative mode.
          </para>
        </simplesect>


        <simplesect id="texts:notices:conf">
          <title>Conference notices</title>

          <para>
            Conference notices are not used in this client. They can
            be set and removed by the conference supervisor using
            &fn:kom-change-conf-motd; and &fn:kom-unset-conf-motd;,
            respectively.
          </para>
        </simplesect>

        <simplesect id="texts:notices:pers">
          <title>Person notices</title>

          <para>
            Notices may be attached to letterboxes. In a strictly
            technical sense, these notices are conference notices, but
            from the perspective of the user they are different. When
            writing a text with a lettterbox as a recipient, any
            notice on that letterbox will be shown, and confirmation
            is required to submit the text.
          </para>

          <para>
            Person notices are set and removed by the conference
            supervisor using &fn:kom-change-conf-motd; and
            &fn:kom-unset-conf-motd;, respectively.
          </para>
        </simplesect>

      </section>

      <section id="texts:faqs">
        <title>FAQs</title>

        <para>
          A FAQ is a regular text that is linked to one or more
          conferences through a FAQ link. The purpose of a FAQ is to
          answer questions that are frequently asked in the
          conference. If the list of questions is small, it is not
          uncommon to use the conference presentation instead. It is
          also possible to attach a FAQ to the server itself.
        </para>

        <para>
          A FAQ is considered unread as a FAQ until you read it using
          one of the special FAQ-related commands in the context of a
          particular conference. If a text you have read is added as a
          FAQ to a conference, it will become an unread FAQ for that
          conference, and will be shown the next time you enter the
          conference. If it is later added as a FAQ to another
          conference, it will become an unread FAQ for
          <emphasis>that</emphasis> conference, despite the face that
          you have read it twice.
        </para>

        <para>
          With default settings, unread FAQs are listed and shown each
          time you enter a conference or log on to the server. When
          you enter a conference, FAQs that are unread in that
          conference are listed and shown. When you log on to the
          server, unread FAQs that are attached to the server are
          listed.
        </para>

        <para>
          To list all FAQs that are attached to a conference, use
          &fn:kom-status-conf; (FAQs are listed as part of the status)
          or &fn:kom-review-presentation; (in which case FAQs are
          listed after the conference presentation). To list all
          conferences attached to the server, use
          &fn:kom-status-server; (FAQs are listed as part of the
          status).
        </para>

        <para>
          To view FAQs for a particular conference, use
          &fn:kom-review-faq;. To view FAQs for the server, use
          &fn:kom-review-server-faq;.
        </para>

        <para>
          In the elisp client the link is created with one of the
          commands &fn:kom-add-faq; or &fn:kom-change-conf-faq;, and is
          removed using &fn:kom-del-faq;. There are similar commands
          for manipulating server FAQs; these can only be used by
          users with administrative rights to the LysKOM server.
        </para>

        <para>
          There are a number of settings that affect FAQs.
          &var:kom-auto-list-faqs; controls automatic listing of FAQs
          when entering conferences. &var:kom-auto-review-faqs;
          controls automatic reviewing of FAQs when entering
          conferences.
        </para>

      </section>
    </section>
  </chapter>
</book>
