Skip to content

Latest commit

 

History

History
 
 

rosdocs

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
  <title>RosDocs Primer</title>
  <articleinfo>
    <releaseinfo>$Id: readme.dbk,v 1.1 2003/06/03 21:28:21 ea Exp $</releaseinfo>
    <author>
      <surname>KJK::Hyperion</surname>
      <personblurb>
        <para>your beloved librarian</para>
      </personblurb>
    </author>
    <copyright>
      <year>2003</year>
      <holder>Reactos Development Team</holder>
    </copyright>
    <revhistory>
      <revision>
        <revnumber>1.1</revnumber>
        <date>2003-06-03</date>
        <authorinitials>EA</authorinitials>
        <revdescription>
          <para>Converted to Docbook 4.1.2.</para>
        </revdescription>
      </revision>
      <revision>
        <revnumber>1.0</revnumber>
        <date>2003-01-20</date>
        <authorinitials>KH</authorinitials>
        <revdescription>
          <para>initial version</para>
        </revdescription>
      </revision>
    </revhistory>
  </articleinfo>
  <sect1>
    <title>FOREWORD</title>
    <para>This document should be written in RosDocs, to demonstrate its power. But since RosDocs is, let&#39;s be frank,
    vaporware, and since I&#39;m still looking for an XML editor that <simplelist><member>1) doesn&#39;t suck and </member><member>2)
    isn&#39;t written in Java</member></simplelist> (but this is a bit redundant), <emphasis>and</emphasis> since I was supposed
    to finish this document some two weeks ago, hand-formatted plaintext wins, for the moment. It should be a matter of half a
    hour with lex+yacc to write a converter.</para>
    <para>Also note that &#34;Win32&#34; and &#34;NT&#34; are trademarked. In this document you&#39;ll never find mentions of
    &#34;Win32&#34; or &#34;NT&#34;, but &#34;Ros32&#34; and &#34;Native&#34; - and you&#39;re encouraged to do the same, except
    when exclusively talking about Microsoft&#39;s implementation (for example, to document a function&#39;s availability on
    various Microsoft products). In abbreviations and identifiers, don&#39;t use &#34;w32&#34;, &#34;win32&#34; or &#34;nt&#34;,
    except for Microsoft-specific code and documentation, or as an abbreviation of the families of system calls (i.e. Nt*,
    NtUser* and W32k*) - in all other cases, use &#34;r32&#34;, &#34;ros32&#34; and &#34;ntv&#34;, respectively. Avoid using
    &#34;Windows&#34; in the same contexts as well - use &#34;ReactOS&#34;. And remember that Alphonse Capone wasn&#39;t jailed
    for extortion and mass murder, but for tax evasion.</para>
  </sect1>
  <sect1>
    <title>CONCEPTS</title>
    <para>RosDocs, in its current incarnation, is a fairly complex documentation system, but that can still be managed and
    authored with simple and promptly available tools, such as text editors and file managers (yet allowing for more
    sophisticated tools to be developed in the future).</para>
    <para>It&#39;s not vital to grasp all the concepts behind RosDocs to start authoring documentation for the ReactOS project,
    since one of the tenets of RosDocs is the strict separation between content, storage and presentation. Should any of the
    three be found flawed, the other two wouldn&#39;t need to be throwed away as well.</para>
    <para>Let&#39;s spend a few more words about content, storage and presentation:<variablelist><varlistentry><term>CONTENT</term><listitem><para>There&#39;s
    two ways to add content to RosDocs:<variablelist><varlistentry><term>Doxygen comments</term><listitem><para>If you&#39;re
    going to write reference pages (think Unix man pages), this is the format you should get accostumed to. It consists of
    special comments, containing markup that a tool called Doxygen can extract into a variety of formats. If you already know
    JavaDoc, or the QT comment-based documentation system, Doxygen supports those as well.</para><para>There&#39;s currently no
    strict guidelines, since RosDocs is still being planned, so you have a great deal of freedom. Don&#39;t abuse it, though.
    Avoid any structural markup, except paragraphs, lists, etc. And, at the moment, don&#39;t worry about storage as discussed
    in another section of this document.</para></listitem></varlistentry><varlistentry><term>DocBook XML documents</term><listitem><para>Doxygen
    can be abused to write manuals and books, but a better long-term solution is learning the DocBook XML DTD. You can also use
    DocBook for reference pages, but Doxygen is preferred for that. Also note that, at the moment, reference pages are more
    important than guides.</para><para>No guidelines yet for DocBook, either. In general, don&#39;t write books yet. Limit
    yourself to articles. A good starting point is writing short tutorials for the Knowledge Base, since no earth-shaking
    changes are expected in that field.</para></listitem></varlistentry></variablelist></para></listitem></varlistentry><varlistentry><term>STORAGE</term><listitem><para>This
    is where things get tough. Remember, though, that this specification is draft at best. Future directions include:<itemizedlist><listitem><para>support
    for DocBook books;</para></listitem><listitem><para>filling the text of hyperlinks with the title of the target topic;</para></listitem><listitem><para>SELECT
    queries, resolved at compile-time, to build tables of links.</para></listitem></itemizedlist>All things that, with the very
    strict decoupling of content and storage outlined here, would be impossible, or involve run-time processing. For this
    reason, limit yourself to reference pages and Knowledge Base articles. Guides, overviews and examples can wait.</para><para>That
    said, here are the storage concepts of RosDocs:<variablelist><varlistentry><term>DOMAINS</term><listitem><para>If you are
    familiar with other schemes featuring domains, such as Internet host names, or the Java third-party classes, this is nearly
    the same. Otherwise, read on.</para><para>Since some package names are awfully common, and since third-party contributions
    are encouraged, it&#39;s necessary to compartment package names on a vendor, product and, for complex products, feature
    basis. Such namespaces are encoded as follows:</para><para><function>[ [ &#60;<replaceable>vendor-specific subdivision</replaceable>&#62;.
    ]&#60;<replaceable>scope</replaceable>&#62;. ]&#60;<replaceable>vendor</replaceable>&#62;</function></para><para>The
    <emphasis>scope</emphasis> can be a product or book name, as in the following examples:<itemizedlist><listitem><para>ReactOS
    Platform SDK: psdk.reactos;</para></listitem><listitem><para>GCC manual: gcc.fsf;</para></listitem><listitem><para>Bruce
    Eckel&#39;s Thinking in C++: ticpp.eckel.</para></listitem></itemizedlist></para><para>Further, optional
    <emphasis>subdivisions</emphasis> are possible:<itemizedlist><listitem><para>GCC internals manual: guts.gcc.fsf.</para></listitem></itemizedlist></para><para>Note,
    however, that, at the moment, only the following domains are accepted:<itemizedlist><listitem><para>psdk.reactos (ReactOS
    Platform SDK);</para></listitem><listitem><para>ssdk.reactos (ReactOS Subsystem Development Kit);</para></listitem><listitem><para>ddk.reactos
    (ReactOS Driver Development Kit);</para></listitem><listitem><para>kb.reactos (ReactOS Knowledge Base).</para></listitem></itemizedlist></para></listitem></varlistentry><varlistentry><term>PACKAGES</term><listitem><para>Packages
    are collections of topics and indexes. They are the base unit of storage. A package may additionally contain one or more of
    the following items:<itemizedlist><listitem><para>secondary indexes;</para></listitem></itemizedlist><itemizedlist><listitem><para>a
    table of contents;</para></listitem></itemizedlist><itemizedlist><listitem><para>configuration metadata.</para></listitem></itemizedlist></para><para>Packages
    are an interface that exposes topics and indexes, they don&#39;t dictate a specific implementation, neither in their
    &#34;source&#34; nor in their &#34;compiled&#34; form. Possible implementations of the compiled form (&#34;engines&#34;)
    include:<itemizedlist><listitem><para>database on a remote server;</para></listitem></itemizedlist><itemizedlist><listitem><para>filesystem
    directory</para></listitem></itemizedlist><itemizedlist><listitem><para>compressed archive.</para></listitem></itemizedlist></para><para>There&#39;s
    no well-defined standard for the source form yet, but it&#39;s expected to be a derivative of DocBook XML. Third parties can
    obviously choose other formats than the future standard for the source form, but official ReactOS documentation will have to
    be written in the standard.</para><para>For your documentation, you&#39;re free to organize your topics in as many packages
    as you like. For ReactOS books and manuals, the following packages are defined:<itemizedlist><listitem><para><emphasis
    role="bold">psdk.reactos</emphasis> domain:<variablelist><varlistentry><term>ros32.</term><listitem><para>The Ros32
    subsystem&#39;s structure and boot sequence; the RPC APIs to the Windows and Console servers; general considerations on the
    API;</para></listitem></varlistentry><varlistentry><term>err.</term><listitem><para>Ros32 error codes; messages, parameters
    and meanings;</para></listitem></varlistentry><varlistentry><term>base.</term><listitem><para>Basic Ros32 APIs. These
    include file, device and console I/O and control; registry, memory, handles, thread, process and service management; DLL
    loading; and basic error handling;</para></listitem></varlistentry><varlistentry><term>ui.</term><listitem><para>Basic Ros32
    user interface APIs. These include windows, MDI windows, window classes, resources, hooks, DDE, keyboard and mouse input,
    and standard controls;</para></listitem></varlistentry><varlistentry><term>gdi.</term><listitem><para>Ros32 GDI and printer
    spooler APIs;</para></listitem></varlistentry><varlistentry><term>rtl.</term><listitem><para>Ros32 Runtime Library support.
    These include string formatting, large integer support and interlocked memory access;</para></listitem></varlistentry><varlistentry><term>ipc.</term><listitem><para>Ros32
    APIs to synchronization objects, shared memory, named and anonymous pipes, and mailslots;</para></listitem></varlistentry><varlistentry><term>sec.</term><listitem><para>Ros32
    interfaces to access control; standard access rights for Ros32 object types; GINA API and implementation; Network Providers
    API and implementation; general security considerations and guidelines;</para></listitem></varlistentry><varlistentry><term>dbg.</term><listitem><para>Ros32
    debugger API; Ros32 SEH support;</para></listitem></varlistentry><varlistentry><term>psapi.</term><listitem><para>Process
    Status Helper API;</para></listitem></varlistentry><varlistentry><term>tlhlp.</term><listitem><para>Tool Helper API;</para></listitem></varlistentry><varlistentry><term>commdlg.</term><listitem><para>Common
    Dialog Box Library;</para></listitem></varlistentry><varlistentry><term>commctrl.</term><listitem><para>Common Controls
    Library.</para></listitem></varlistentry></variablelist></para></listitem><listitem><para><emphasis role="bold">ssdk.reactos</emphasis>
    domain:<variablelist><varlistentry><term>ntv.</term><listitem><para>ReactOS Native architecture; system structure and boot
    sequence; RPC API to the Base server; the Process Environment Block; the Thread Environment Block; the Kernel/User Shared
    Data;</para></listitem></varlistentry><varlistentry><term>err.</term><listitem><para>NTSTATUS error codes; messages,
    parameters and meanings;</para></listitem></varlistentry><varlistentry><term>obj.</term><listitem><para>Native objects and
    handles; overview of predefined object types; Object Manager basics; the system objects namespace;</para></listitem></varlistentry><varlistentry><term>sec.</term><listitem><para>The
    Native security model; explanation of token objects; SIDs, ACEs and ACLs; generic access rights; standard access rights for
    kernel object types;</para></listitem></varlistentry><varlistentry><term>seh.</term><listitem><para>Structured Exception
    Handling internals;</para></listitem></varlistentry><varlistentry><term>lpc.</term><listitem><para>The Local Procedure Call
    protocol;</para></listitem></varlistentry><varlistentry><term>dbg.</term><listitem><para>Debugging interfaces, both kernel
    and user mode; the debugger LPC protocol;</para></listitem></varlistentry><varlistentry><term>ntzw.</term><listitem><para>System
    calls (Nt* and Zw*), both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>rtl.</term><listitem><para>Runtime
    library interfaces, both kernel and user mode; list of supported C runtime interfaces, both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>ldr.</term><listitem><para>The
    PE Loader API (Ldr*), both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>csr.</term><listitem><para>The
    Client-Server Runtime API (Csr*); server modules API and implementation;</para></listitem></varlistentry><varlistentry><term>nls.</term><listitem><para>National
    Language Support API (Nls*), both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>ntuser.</term><listitem><para>Native
    User Interface (NtUser*) system calls, both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>w32k.</term><listitem><para>Native
    GDI (W32k*) system calls, both kernel and user mode;</para></listitem></varlistentry><varlistentry><term>peexe.</term><listitem><para>Structure
    and semantics of the PE executable format.</para></listitem></varlistentry></variablelist></para></listitem><listitem><para><emphasis
    role="bold">ddk.reactos</emphasis> domain:<variablelist><varlistentry><term>err.</term><listitem><para>Bugcheck codes;
    messages, parameters and meanings;</para></listitem></varlistentry><varlistentry><term>ke.</term><listitem><para>The Kernel;
    architecture and API;</para></listitem></varlistentry><varlistentry><term>hal.</term><listitem><para>The Hardware
    Abstraction Layer; architecture and API;</para></listitem></varlistentry><varlistentry><term>cc.</term><listitem><para>The
    Cache Manager subsystem; architecture and API;</para></listitem></varlistentry><varlistentry><term>cm.</term><listitem><para>The
    Configuration Manager subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>ex.</term><listitem><para>The
    Executive Support subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>io.</term><listitem><para>The
    I/O Manager subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>kd.</term><listitem><para>Kernel
    debugging; protocols and API;</para></listitem></varlistentry><varlistentry><term>ki.</term><listitem><para>Predefined
    interrupt handlers;</para></listitem></varlistentry><varlistentry><term>lpc.</term><listitem><para> The Local Procedure Call
    subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>mm.</term><listitem><para>The
    Virtual Memory Manager subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>ob.</term><listitem><para>
    The Object Manager subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>ps.</term><listitem><para>The
    Process Structure Manager subsystem; architecture and API; implemented object types;</para></listitem></varlistentry><varlistentry><term>se.</term><listitem><para>The
    Security Reference Monitor subsystem; architecture and API; iimplemented object types.</para></listitem></varlistentry></variablelist></para></listitem></itemizedlist></para></listitem></varlistentry><varlistentry><term>TOPICS</term><listitem><para>Topics
    are the base unit of documentation. They contain the actual content, and are organized in physical units of storage called
    packages.</para><para>[placeholder]</para></listitem></varlistentry><varlistentry><term>INDEXES</term><listitem><para>Indexes
    are an addressing mechanism to retrieve a topic from a package. Addresses in an index are strings, called keys, associated
    to each topic in their source form. There&#39;s essentially two kinds of indexes:<itemizedlist><listitem><para>Identification
    indexes. They provide a many-to-one mapping between keys and topics. That is, a topic can be pointed at by one or more keys
    in the same identification index. Identification indexes are typically used for unambiguous identification of topics.</para><para>Currently,
    a number of predefined identification indexes are defined. There&#39;s a strong bias towards developer&#39;s documentation
    at the moment, but it will be solved by specializing generic indexes. Here are the generic identification indexes currently
    defined:<variablelist><varlistentry><term>page.</term><listitem><para> Self-contained documents containing detailed
    information about a specific topic. Examples include Knowledge Base articles, reference pages of user commands, library
    functions, etc. They usually contain links to related references or sections;</para></listitem></varlistentry><varlistentry><term>section.</term><listitem><para>Any
    topic with structural meaning, i.e. not self-contained. They usually contain links to child sections or references.</para></listitem></varlistentry></variablelist></para><para>For
    developer&#39;s documentation, the following specialization of the <emphasis>section index</emphasis> are defined:<variablelist><varlistentry><term>subsection.</term><listitem><para>A
    subsection of strongly-related topics;</para></listitem></varlistentry><varlistentry><term>overview.</term><listitem><para>Pages
    containing general information about a subsection;</para></listitem></varlistentry><varlistentry><term>example.</term><listitem><para>Pages
    containing code samples about a subsection;</para></listitem></varlistentry><varlistentry><term>reference.</term><listitem><para>Pages
    with an index of detailed information about a subsection. The distinction between &#34;overview&#34;, &#34;example&#34; and
    &#34;reference&#34; indexes is necessary to simplify authoring, since, this way, the root subnodes of a subsection can be
    given the same key, as in the following example:<screen> TOC                       | Index[key]
---------------------------+-----------------------------
 User Interface            | &#60;none&#62;
  + ReactOS User Interface | section[rosui]
    + Windowing            | section[windowing]
       + Windows           | subsection[windows]
          + Overview       | overview[windows]
          + Examples       | example[windows]
          + Reference      | reference[windows]</screen></para><para>For an analogous reason, there&#39;s a further
    specialization for child nodes of reference sections to create indexes of functions, structures, macros, etc. These
    specialized indexes are:<variablelist><varlistentry><term>functions.</term><listitem><para>Functions other than class
    methods;</para></listitem></varlistentry></variablelist><variablelist><varlistentry><term>structures.</term><listitem><para>Types
    declared with the C/C++ struct or union constructs, and that have no methods;</para></listitem></varlistentry></variablelist><variablelist><varlistentry><term>enumerations.</term><listitem><para>Types
    declared with the C/C++ enum construct;</para></listitem></varlistentry></variablelist><variablelist><varlistentry><term>types.</term><listitem><para>Integral,
    array or pointer types with a special meaning;</para></listitem></varlistentry></variablelist><variablelist><varlistentry><term>constants.</term><listitem><para>Groups
    of macros that comply with the following requirements:<itemizedlist><listitem><para>they have no parameters;</para></listitem><listitem><para>they
    can be fully evaluated at compile time;</para></listitem><listitem><para>they are strongly related. For example, they are
    interchangeable values for the same parameter, or flags, or both;</para></listitem><listitem><para>they are referenced from
    more than one reference page. If they are referenced just once, they must be documented in the page that references them.</para></listitem></itemizedlist></para></listitem></varlistentry><varlistentry><term>errors.</term><listitem><para>Specialization
    of the constants index. Constants used to return status codes;</para></listitem></varlistentry><varlistentry><term>macros.</term><listitem><para>Macros,
    or groups of macros, that comply with at least one of the following requirements:<itemizedlist><listitem><para>they have
    parameters;</para></listitem></itemizedlist><itemizedlist><listitem><para>they are used for conditional compilation;</para></listitem></itemizedlist><itemizedlist><listitem><para>they
    are used as declaration modifiers;</para></listitem></itemizedlist><itemizedlist><listitem><para>they have side effects.</para></listitem></itemizedlist></para><para>Function
    aliases for type-generic string handling (_t* for the C runtime and *W/*A for the Ros32 API) are excluded, and must be
    documented as functions (in all their possible variants for the C runtime, and in their type-generic form for the Ros32
    API). Macros returning l-values (e.g. <varname>errno</varname>) should be listed in the objects index;</para></listitem></varlistentry><varlistentry><term>interfaces.</term><listitem><para>Abstract
    classes;</para></listitem></varlistentry><varlistentry><term>classes.</term><listitem><para>Classes with an implementation;</para></listitem></varlistentry><varlistentry><term>objects.</term><listitem><para>Statically
    allocated memory objects. The type of such objects should be documented separatedly;</para></listitem></varlistentry><varlistentry><term>messages.</term><listitem><para>Window
    messages;</para></listitem></varlistentry><varlistentry><term>notifications.</term><listitem><para>Window messages delivered
    through WM_NOTIFY.</para></listitem></varlistentry></variablelist></para></listitem></varlistentry><varlistentry><term>guide.</term><listitem><para>Root
    node of a guide/how-to/tutorial.</para></listitem></varlistentry></variablelist></para></listitem></itemizedlist><itemizedlist><listitem><para>Search
    indexes. They provide a one-to-many mapping between keys and topics. That is, a key in a search index can point to one or
    more topics. Search indexes are typically used for keyword searches among many topics</para></listitem></itemizedlist></para><para>[placeholder]</para></listitem></varlistentry><varlistentry><term>TOCS</term><listitem><para>[placeholder]</para></listitem></varlistentry><varlistentry><term>CATALOGS</term><listitem><para>[placeholder]</para></listitem></varlistentry></variablelist></para></listitem></varlistentry><varlistentry><term>PRESENTATION</term><listitem><para></para></listitem></varlistentry></variablelist></para>
  </sect1>
  <sect1>
    <title>AUTHORING</title>
    <para>[placeholder]</para>
    <sect2>
      <title>USING DOXYGEN</title>
      <para>[placeholder]</para>
    </sect2>
    <sect2>
      <title>USING DOCBOOK</title>
      <para>[placeholder]</para>
    </sect2>
    <sect2>
      <title>GUIDELINES</title>
      <para>[placeholder]</para>
    </sect2>
  </sect1>
</article>