Conference vaxuum::online_bookbuilding

74.0. "Section References in DW_END Doctype" by BOOKIE::LAQUERRE () Tue Jan 31 1989 18:42

    This change to the DECwindows Documentation Style Guide is important
    to those who are building online books, so I'm posting it here as
    well.
    
    Peter
    
    ----------------------------
    
           <<< 4TRACK::DUA0:[NOTES$LIBRARY]DECWINDOWS_DOCUMENTATION.NOTE;1 >>>
                         -< DECwindows Documentation >-
================================================================================
Note 151.0            Change to DECwindows Doc Style Guide            No replies
BOOKIE::LAQUERRE                                     67 lines  31-JAN-1989 18:37
--------------------------------------------------------------------------------


          DIGITAL       INTEROFFICE MEMORANDUM


          TO:      DECwindows Writers and    DATE: 30-January-1989
                   Editors                   FROM: Peter LaQuerre
                                             DEPT: Corporate User Pub-
                                                   lications
                                             EXT:  381-2127
                                             LOC:  ZKO2-2/R94
                                             ENET: ORION::LAQUERRE

          cc:      Louise Breen 

          SUBJECT: Change to DECwindows Documentation Style Guide


          The first bullet item on page 1-11 of the DECwindows Doc-
          umentation Style Guide recommends the following wording for
          references to another section in the same chapter:

               For more information about work-in-progress boxes, 
	       see the section Standard Dialog Boxes.

          This convention was designed for the DECWINDOWS_ENDUSER
          (DW_END) doctype.  DW_END is an unnumbered head doc-
          type and we felt the words "the section" would be helpful
          to the user.

          However, experience in online bookbuilding has shown us that
          this convention is not acceptable when books are built for
          the Bookreader because the ONLINE doctype uses numbered heads.

          As a result, we are modifying the DECwindows Documentation
          Style Guide so the words "the section" are removed from the
          cross-reference. The example at the top of page page 1-11,
          should now read as follows:

               For more information about work-in-progress boxes, see 
	       Standard Dialog Boxes.

          Writers should modify their references so the words "the
          section" are not hard-coded into the SDML file. For exam-
          ple, the following coding is not acceptable for the online
          Bookreader:

	       .
	       .
	       <p>
               For more information about work-in-progress boxes, 
	       see the section <REFERENCE>(standard_dialog_boxes).
	       .
	       .

          The following coding is acceptable:

	       .
	       .
	       <p>
               For more information about work-in-progress boxes, see
               <REFERENCE>(standard_dialog_boxes).
	       .
	       .

          If you have any questions about this change in the DECwin-
          dows Documentation Style Guide, please send mail to 
	  4TRACK::LAQUERRE.