From 731e4f41708269a93841ec08d787913ea45e191d Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Tue, 19 Sep 2000 19:20:00 +0000 Subject: [PATCH] DocBook V1.2 --- docbook/sgml/README | 27 + docbook/sgml/ch03.sgm | 1904 ++++++++++++++++++++++++++++++ docbook/sgml/docbook1.0.dtd | 683 +++++++++++ docbook/sgml/docbook1.2.doc.sgml | 1094 +++++++++++++++++ docbook/sgml/docbook1.2.dtd | 929 +++++++++++++++ docbook/sgml/sgml.declaration | 66 ++ docbook/sgml/xlsc.sgm | 74 ++ 7 files changed, 4777 insertions(+) create mode 100644 docbook/sgml/README create mode 100644 docbook/sgml/ch03.sgm create mode 100644 docbook/sgml/docbook1.0.dtd create mode 100644 docbook/sgml/docbook1.2.doc.sgml create mode 100644 docbook/sgml/docbook1.2.dtd create mode 100644 docbook/sgml/sgml.declaration create mode 100644 docbook/sgml/xlsc.sgm diff --git a/docbook/sgml/README b/docbook/sgml/README new file mode 100644 index 000000000..524325c58 --- /dev/null +++ b/docbook/sgml/README @@ -0,0 +1,27 @@ +README + +This directory contains several versions of the DocBook DTD, +their documentation, an SGML declaration, and some sample files. +As of 2 March 1993 two versions of this DTD are available, 1.0 +(for historical reference) and 1.2 (the current version). +The documentation for DTD version 1.0 is out of date, +but may still be useful, especially for RefEntries (man pages). + +As of 2 March 1993 the documentation for the DTD version 1.2 consists of +an alphabetical list of elements, with definitions. This list +is available in both PostScript and SGML formats. +Additional documentation will be forthcoming. + +DocBook 1.2 is an expanded and revised version of 1.0, including +many in-line elements, some specific, some general and inclusive. +Valid documents may of course be constructed with a subset of +these in-line elements---don't feel you must use them all. + +The DTD does not establish detailed rules for the usage of +elements. This is a matter for editors and writers to deal with. + +Please note that the DTD has an associated SGML declaration, +also to be found in this directory. + +To get all of the files relevant to version 1.2, obtain the file +named docbook1.2.shar. diff --git a/docbook/sgml/ch03.sgm b/docbook/sgml/ch03.sgm new file mode 100644 index 000000000..812ab65d6 --- /dev/null +++ b/docbook/sgml/ch03.sgm @@ -0,0 +1,1904 @@ + + +Working in the X Environment +Working in the X Environment + +This chapter shows you how to begin working productively in the X +environment. It describes how to: + + + +Open a second xterm window. + + + +Move windows; raise windows to the front of the display; convert +windows to icons. + + + +Close an xterm window. + + + +Start other clients in convenient places on the display. + + + +Run clients on remote machines. + + + +Customize a single client process using command-line options. + + + +Specify alternate default characteristics for a client using resource variables. + + + +At the end of the last chapter, you should've had the X server, the +first xterm window, and the mwm window manager running. +The current chapter +illustrates some of the system's basic capabilities +so you can begin working more productively. This chapter shows you how to: + + + +Open a second xterm window. + + +Use the pointer to affect windows on the display. + + +Iconify, deiconify, maximize, raise, move, resize, and close windows +using the pointer on the mwm frame. + + +Close an xterm window from the command line. + + +Start additional client programs, on both local and remote machines. + + +Organize the display. + + +This chapter also introduces some basic ways +to customize X clients to better suit your needs. + +Creating Other Windows +windowscreating +Once you focus input on the first xterm window, as described in +Chapter 2, you can enter +commands to open other client windows. For example, +you can open a second xterm window by typing this +command at the prompt in the first xterm window: +xterm (terminal emulator)multiple xterms + +% xterm + +After a few moments, a second xterm window will be displayed on the +screen. As we'll see later in this chapter, you can specify the +location for a new window using a command-line option (or in many cases using a resource variable +stored in a file in your home directory). +If you don't specify +position on the command line (or in a resource +file), by default mwm +automatically places +new windows offset from the upper-left corner of +the screen, as shown in +Figure 3-1. + +If you start multiple processes in a row, the windows will be placed +progressively further from the upper-left corner (towards the opposite +corner), so that no window completely overlaps another. + +windowsplace using pointer +interactivePlacement +You can customize mwm to allow you to place new windows +interactively using the pointer. This modification is performed +by setting a resource variable called interactivePlacement +to a value of true. +See Chapter 13 for instructions on modifying mwm. +See the mwm reference page in Part Three of this guide for +more information about interactivePlacement. + + + +
+mwm automatically places the second xterm window + +
+The new xterm window displays a +prompt from whatever shell you are using. In this case, the new window is +running the UNIX C shell. + +Notice that the second window's frame is a dark gray, indicating that input +is focused on it. +The first window's frame has changed from dark to light gray; it no longer +has the input focus. +It's important to be aware that when +you start a new window (and click-to-type focus is being used), the +new window automatically takes over the input focus. +(Note that the colors may vary according to system defaults.) + +windowsswitching between +In the default mwm configuration, +to switch back and forth between windows you must move the pointer +from one window to the other and click the first button. +Notice that if you are working with a stack of windows that overlap, +selecting a window as the active window automatically raises that window +to the top of the stack (in effect, the front of the display). + +Whatever you type will appear in the window with the highlighted frame. +Try starting a command in both windows. For example, start up +vi or another text editor in the second xterm window. +Notice how you can switch back to the first window to type a new +command, by moving the pointer and clicking--even if you +leave vi in +insert mode or some other command in the process of sending output to +the screen. Whatever process was running in the window you left will +continue to run. If it needs input from you to continue, it will wait. +windowsmultiple + +You must always switch focus to work with multiple windows. However, +mwm has complicated matters by placing the second xterm +window in Figure 3-1 + in a very inconvenient place. The second +window overlies the first window and almost completely obscures it. + +Windows commonly overlap on +the display. The window manager allows you to change the position and +size of windows so that you can work effectively in such situations. + +The primary window management tool mwm provides is the window frame. +The section “Managing Windows Using the mwm Frame,” later in this +chapter, +shows you how to perform these functions simply by using the pointer on +various parts of the frame. But before we can learn to perform these window +management functions, we need to learn more about pointer actions. + +Using the Pointer +pointerusing +As explained in Chapter 1, the cursor on the screen follows the +pointer's movement on the desktop. Move your pointer +around on the desk to get used to this. Keep in mind that +different pointers respond differently. If you move to another +display, the screen cursor may move more quickly or slowly than the +one you're used to. The xset client (described +in &cmtf14;) lets you modify pointer behavior. + +buttonpointer +You use the pointer to indicate a graphical element on the screen, +such as a window, icon, or command button. Most pointers have +three buttons. For our purposes, we'll refer to these buttons +as first, second, and third, where the first button is the leftmost +on the pointer, the second is in the middle, and third is the +rightmost. + +Keep in mind that “first” is a logical distinction +made by X, not a physical one. The first logical pointer button generally +corresponds to the leftmost button on the pointer. +(Thus, in some contexts you may find the buttons referred to as left, middle, +and right.) +However, X allows you to +change the correspondence of logical and physical buttons. For +example, you can reassign +the first logical button to be the rightmost button on the pointer. +A lefthanded person might opt to reverse the order of the buttons. +You remap pointer buttons using a client called xmodmap, which +is described in detail in &cmtf14;. + + +By placing the pointer on a particular element and then +performing some button action (and possibly a pointer motion), you can +invoke a variety of +commands. The types of button actions and pointer motions you can perform are: + + + +Click + +clicking buttons +buttonclicking +To click a button, you press the pointer button down and release it. +A click is a rapid action; there is no pause between the press and +release. A double click is two full clicks in succession, with no +pause between clicks. A triple click is three clicks in +succession. + + +Press + +buttonpressing +To press a button, you push the button down and hold it down. + + +Release + +buttonreleasing +After pressing a button down, you release it by letting up on the button. + + +Drag + +pointerdragging item with +dragging items +To drag a graphical object (such as a window or icon) from one +location on the screen to another: place the pointer on the object; +press one or more pointer buttons; move the pointer to another +location (dragging the object); and release the button(s). + + +Keep in mind that +some commands or actions are invoked by a simple click on +a particular graphic element, as illustrated by mwm's +click-to-type focus. Alternatively, some actions require a button +press and pointer motion (i.e., dragging). + +When dragging is used to move an object, +the actual object does not appear in the new location until you +complete the movement and release the pointer button. Instead, you +appear to drag an outline representing the object. +When you release the pointer button, the actual object appears in the +new location. This effect is illustrated in the section “Moving a Window,” +later in this chapter. + +Dragging is also commonly used to change the size of a window. +Again, an outline indicates that the window's size is changing. When +the outline approximates the size you want, you release the pointer +button and the actual window is redrawn using the selected dimensions. + +The following sections describe how to perform the most basic window +management functions, which require you to use the pointer in the ways +we've discussed. +pointerusing + + +Managing Windows Using the mwm Frame +mwm (Motif window manager) +Figure 3-2 +shows an xterm window “framed” by mwm. +The window frame itself and several features of it +are tools that allow you to manage the window using the pointer. + +
+An xterm window framed by mwm + +
+command buttonsMinimize +The wider top edge +of the frame is the titlebar. The titlebar is +composed of several parts including a title area (displaying the +name of the application) and three command buttons (Minimize, Maximize, +and Window Menu). Notice that whenever you move the pointer into the +titlebar, the pointer changes to the arrow cursor. + +Though it's not apparent from Figure 3-2, + you can perform most window +management functions by using the pointer on various parts of the frame. +titlebar +The following sections explain how to +iconify, maximize, move, raise, resize, and close windows using the frame. +Chapter 4 describes menu items and keyboard shortcuts +that can be used as alternatives to the frame. +These are important when a window's frame is obscured by other +features of the display. Chapter 4 also describes additional +functions provided by mwm menus. + +Converting a Window to an Icon +windowsiconifying +Minimize command button +command buttonsMinimize +iconifying windows +As discussed in Chapter 1, an icon is a symbol that represents a +window in an inactive state. There are many circumstances in which +it might be desirable to iconify a window: + + + +To prevent yourself from inadvertently terminating a window, as in +the case of the login xterm. + + +While running a program whose progress you don't need to +monitor; if a window is tied up running a process and you don't have +to see it, the window is just taking up space. + + +If you are only using an application occasionally. +For example, you might be +running the xcalc calculator program, but +only using it every so often. + + +If you want to use several application windows, but only display a few at a +time; this arrangement can be somewhat less confusing than a display crowded +with windows. Having some windows iconified also frees you from +constantly shuffling the stacking order. + + +The Minimize command button on the mwm frame allows you to +convert a window to an icon (iconify it). +The Minimize button appears immediately to the right of the title area +and is identified by a tiny square in its center. +To iconify a window, use the following steps: + + + +Place the pointer within the Minimize command button. The pointer simply +has to rest within the button's outer border, not within the tiny square +identifying it. + + +Click the first pointer button. The window is iconified. +Figure 3-3 +shows a window being converted to an icon in this way. + + +By default, icons are displayed in the bottom left corner of the root +window. mwm can also be set up to place icons in another location, +to allow you to place them interactively using the pointer, or +to organize icons within a window +known as an icon box. In &cmtf13;, we'll discuss the +specifications necessary to set up an icon box. + +
+Converting a window to an icon with the Minimize button + +
+Minimize command button +command buttonsMinimize + +Converting an Icon to a Window +windowsdeiconifying +deiconifying windows +iconsconverting to windows +To convert an icon back to a window (deiconify it), place the pointer +on the icon and double click, using the first pointer button. +The window is redisplayed in the position it appeared before it was +iconfied (and is also raised to the top of the stack). + +Between the first and second clicks, you'll probably notice +that another small window is displayed for an instant above the icon. +This window is actually a menu, called the Window Menu. +(This menu can be displayed from a window or from an icon and can be +used to invoke several window management functions on the window or +icon. We'll discuss the Window Menu in more +detail in &cmtf04;.) + +Be aware, however, that if you pause too long between the two clicks +in deiconifying a window, the second click will not be interpreted +and the icon will not be converted back to a window. +Instead the Window Menu will remain on the screen, as in +Figure 3-4. + +Notice that in addition to displaying the menu, +clicking has caused the icon image to change in appearance. +The icon label is wider and the +label and the frame surrounding the icon are highlighted. +These changes indicate that the icon has the input focus; thus the +icon will interpret subsequent +keystrokes as window manager commands. + +Notice also that the first item on the +menu, Restore, is surrounded by a box, indicating that +it is available for selection. Restore means to +restore an icon to a window (or, as we'll see, a maximum size window to +its original size). When the Window +Menu0 is displayed above an icon, you can convert the icon to a +window by placing the pointer on the Restore menu item +and clicking the first pointer button. +(Whenever a Window Menu item is boxed, you can also +select it by pressing either the Return key or the space bar.) + +
+Window Menu being displayed over an icon + +
+If you want to remove the +menu without invoking a command, simply move the pointer off the +icon and menu and click the first pointer button. +The menu will be removed; however, the icon will retain the input +focus--the label and border will remain +highlighted--until you focus input on another window or icon. + + +Maximizing a Window +buttoncommand +command buttonsMinimize +Minimize command button +command buttonsMaximize +windowsminimizing +windowsmaximizing +Maximize command button +windowsenlargening +Maximizing a window generally means enlarging it to the size of the root +window. (In some cases, a client application may specify its +own maximum window size and maximizing will produce a window of this size.) +This action can be performed using the Maximize command button, which +is located to the right of the Minimize command button (in the upper-right +corner of the window). + +The Maximize command button is identified by +a larger square in its center. +It allows you both to enlarge the window to the size of +the root window (or to the maximum size the client allows), and +once it has been enlarged, to convert it back to its original size. + +To maximize a window, use the following steps: + + + +Place the pointer within the Maximize command button. The pointer simply +has to rest within the button's outer border, not within the square +identifying it. + + +Click the first pointer button. The window is maximized, as +illustrated in +Figure 3-5. + + +
+A maximized window + +
+The large window should function in the same way it did before it was +maximized. Theoretically, you can maximize an xterm window to have a +single, very large terminal screen. However, be aware that certain +programs you may run within an xterm, such as the vi text +editor, do not always work properly +within a window of this size (even if you've used the +resize +client, as described in &cmtf05;). +The Maximize function is more safely +used with an application that displays a graphic image or performs a +simple function, such as xclock. + +Also, some client programs that do not +support resizing, such as the Release 3 version of xcalc, cannot +xcalc (calculator)and resizing windows +be maximized correctly. +In the case of xcalc, the frame surrounding the +calculator application is maximized, but the actual calculator remains the +same size. + +The Maximize button is a toggle. +To convert a maximized window back to its original size, click on +the Maximize button again with the first pointer button. +The Restore item on the Window Menu will also +perform this function. +Maximize command button + + +Raising a Window or Icon +windowsraising +iconsraising +We've already seen the necessity for raising windows on the display: +frequently windows overlap. In order to work with a window that is +all or partially covered by another window, you'll want to raise it +to the top of the window stack. Using the default mwm, +you raise a window with the following steps: + + + +Place the pointer on any part of the window frame, except the three +command buttons (Minimize, Maximize, and Window Menu). + + +Click the first pointer button. The window is raised to the top of the +stack. + + +When you are using explicit (click-to-type) focus, this click +also selects the window to receive input, i.e., +makes the window the active window. +Once you have raised a window to the top of the stack, you should be +able to enter input and read output easily. + +Windows may obscure icons on the display. (mwm does not allow +one icon to obscure another.) If an icon is partially visible under +a window, you can raise it using the following steps: + + + +Place the pointer on the obscured icon. + + +Click the first pointer button. + + +The icon is raised to the top of the stack. + +Figure 3-6 +illustrates an icon being raised in front of a window. + +Notice that in addition to being raised to the top of the window stack, +a menu (called the Window Menu) +is displayed over the icon. +(This menu can be displayed from a window or from an icon and can +be used to invoke several management functions on the window or icon. +We'll discuss the Window Menu in more detail in Chapter 4.) +To remove the menu, move the pointer off of the icon and menu and +click the first button. + +Notice also that the icon image changes in appearance when you raise the +icon to the top of the stack (as it did when we paused between the double +click to deiconify). +The wider label and the highlighted label and frame +indicate that the icon has the input focus. (Remember, when an icon +has the input focus, it will interpret subsequent +keystrokes as window manager commands.) +Even when you remove the Window Menu, the icon will +retain the focus (and remain highlighted). When you direct focus to another +window (or icon), the icon label will become normal again. + +
+Raising an icon + +
+ +Moving a Window +windowsmoving +title areamwm frame +mwm (Motif window manager)frame;title area +movingwindows +titlebarand moving windows +In many cases you'll want to move a window from one location on the +display to another. +The largest part of +the titlebar is known as the title area, primarily because it +displays the name of the application. +The title area allows you to move the window, using the following steps: + + + +Place the pointer within the title area. The pointer changes to the +arrow cursor. + + +Press and hold down the first pointer button. + + +Move the window by dragging the pointer. +Figure 3-7 +shows a window +being moved in this way. When you begin to move the window, +the pointer changes to a cross arrow pointer and a window outline appears. +This outline tracks the pointer's movement. +In the center of the screen, a small, rectangular box also appears, +displaying the x and y coordinates of the window as you move it. + + +Drag the cross arrow pointer with the window outline to the desired location +on your screen. + + +Release the first pointer button. The window will move to the +selected location. + + +
+Moving a window by dragging the title area + +
+With the default configuration +of mwm, moving a window also selects that window as the active +or focus window. + + +Moving an Icon +iconsmoving +movingicons +Moving an icon is similar to moving a window. To move an icon: + + + +Place the pointer on the icon. + + +Press the first pointer button. + + +Move the icon by dragging the pointer. +Figure 3-8 +shows an icon +being moved in this way. When you begin to move the icon, +the pointer changes to a cross arrow pointer and an icon outline appears. +This outline tracks the pointer's movement. + + +Drag the cross arrow pointer with the icon outline to the desired location +on your screen. + + +Release the first pointer button. The icon will move to the +selected location. + + +With the default configuration +of mwm, moving an icon also selects that icon to receive the +input focus. + +
+Dragging an icon to a new location + +
+mwm (Motif window manager) + +Resizing a Window +windowsresizing +resizing windowsusing pointer +One of the most distinctive and useful features of the mwm window +frame is not at all obvious. The entire frame (other than the titlebar--i.e., +the title area and command buttons) +is designed to allow you to resize the window using the pointer. +Notice that the frame is divided by small lines +into eight sections: four long +borders (two horizontal and two vertical) and four +corners. +Figure 3-9 +shows these sections of the window frame. + +You can resize a window horizontally, vertically, or simultaneously in +both directions. +Resizing is a bit trickier than any of the other window management +functions we've tried, since the way you move the pointer determines +the size of the window. It will probably take some practice. + +If you place the pointer within a window and then move it into one of +the long horizontal or vertical borders, +you'll notice the pointer changes to a new shape: +an arrow (pointing toward the window border), with a short line perpendicular +to it. This short line +represents the window border. Try moving the pointer in this fashion +in one of the windows on your display to get a better idea of what the +pointer looks like. +If you move the pointer from within a window into the outer border at +one of the corners, +the pointer will become an arrow pointing diagonally at a small +corner symbol, as pictured in +Figure 3-10. + Figure 3-11 + shows all of the possible resize pointers. + +
+The outer frame is divided into four long borders and four corners + +
+
+Window with resizing pointer + +
+
+Resizing pointer symbols + +
+Once the pointer changes to one of these shapes, you can move the +border (or corner) of the window. Resizing from one of the long borders +only allows you to change one dimension of the window: a horizontal +border can only be moved up or down, changing the height; a +vertical border can only be moved left or right, changing the width. + +Resizing from a corner offers the most flexibility. You can move a +corner in any direction you choose, changing both dimensions of the +window if you want. For example, you can drag the lower-right corner of +a window down and to the right to enlarge the window in both dimensions. + +You determine the size and shape of the window by choosing the border or corner +you want to extend (or contract) and moving it the desired amount using +the following steps: + + + +Move the pointer from within the window to the border or corner you want +to move. The pointer changes to one of the symbols pictured in +Figure 3-11. + + + +Press and hold down the first pointer button and drag the window border +or corner in the direction you want. As you resize the window, an +image of the moving border(s) tracks the pointer movement. Also, in the +center of the display, a small rectangular window shows the dimensions +of the window as they change (in characters and lines for xterm +windows, in pixels for most other clients). + + +Resize the window as desired. + + +Release the first pointer button. The window is redisplayed in the +new shape. (The border image and window geometry tracking box disappear.) + + +Figure 3-12 +shows a window being “stretched” from the lower-right corner. + +Note that resizing an xterm window will not change the dimensions of +the text currently in the window. If you make the window smaller, +for instance, some of the text may be obscured. On most operating +systems, this should not be a problem. As you continue to work, perhaps +starting a text editor, the +text will be adjusted to display in the newly sized window. +Problems are more likely to +occur if you resize a window during a text +editing session. It's likely that the +text editing program will not +know about the window's new size and will operate incorrectly. +To solve this problem, +simply quit out of the editor +and start another session. + +
+Dragging the corner to make a window larger + +
+If your resized xterm window does not seem to know its new +size, you may be working with an operating system that does not support +terminal resizing capabilities. Refer to the discussion of the +resize client in &cmtf05;, +and to the resize reference page in Part Three of this guide +for alternative solutions. + + +Closing a Window: The Window Menu Button +menusWindow Menu (mwm) +Window Menucommand button +The command button on the left side of the titlebar is used to bring up +the Window Menu, which provides seven items that +can be used to manage the window and its icon. +&cmtf04;, describes how to +bring up the Window Menu and invoke its various functions. + +This command button also has another function. +Double-clicking the first pointer button on the +windowskilling;with Window Menu button +killingwindows +Window Menu command button kills the client program +and closes the window. +Be aware, however, that like other methods of “killing” a program (such as the +xkill client), +double-clicking on the Window Menu button +can adversely affect underlying processes. +Refer to the +section on xkill in &cmtf08;, +for a more complete discussion of the hazards of killing a client and a +summary of alternatives. + +You can customize mwm so that double clicking performs no +function by setting a resource variable, wMenuButtonClick2, to +false. See the sections “Setting mwm Resources” and +“mwm-Specific Appearance and Behavior Resources” in Chapter 13, +and the mwm reference page in Part Three of this guide for details. +windowscreating +menusWindow Menu (mwm) + + +Exiting from an xterm Window +xterm (terminal emulator)terminating +terminating xterm window +killingwindows +windowsexiting xterm +windowsclosing +exitingxterm window +When you are finished using an xterm window, you can +remove it by typing whatever command you usually use to log +off your system. Typically, this might be exit +or Control-D. We'll close the second xterm window in +Figure 3-13 +by typing exit. + +Notice that when we terminate the second xterm window, +the first xterm window takes over the input focus. +When explicit focus is being used and a window is terminated, +the input focus reverts to the window that previously had the focus. + +Be aware that terminating the login xterm window (the first +xterm to appear) kills the X server and all associated clients. +(If xdm is running X, the server will be reset but only after +all client processes have been killed.) Be sure to terminate all +other xterm windows before terminating the xterm login +window. Also, if you are in an editor such as vi, be sure +to save your data before you terminate the window. + +windowsiconifying +iconifying windows +In fact, it may be wise to iconify the login window +and use other xterm windows instead, so that you +don't inadvertently terminate it. Remember: you iconify a window by +placing the pointer on the Minimize command button on the frame and +clicking the first pointer button. + +If you are worried about typing Control-D (end-of-file) accidentally +and you normally use the C shell (csh), you can enter: + +% set ignoreeof + +in the login window. Then typing exit becomes the only way you can +terminate the window. + +Note that some C shell +implementations have an autologout variable, which will +automatically terminate the shell if there is no activity for a given +period of time. +If your C shell supports this feature, be sure to disable it +in the login xterm window using this command: + +% unset autologout + +As an alternative to entering the command used to log off the system, +you can also terminate an xterm +window by selecting Send HUP Signal, Send TERM +Signal, Send KILL Signal, or +Quit from the xterm Main Options menu. (These menu options send +different signals to the xterm process. Depending on what +signals your operating system +recognizes, some of the options may not +work as intended. See Chapter 5 for more information.) + +
+Closing an xterm window + +
+The mwm window manager also provides several ways +to remove an xterm or any other client window, among them +double-clicking on the Window Menu command button, as described +previously. Additional methods are described in &cmtf04;. + + +Starting Additional Clients +clientsstarting additional +Now that you know the basics of managing windows, +you can start other X clients just like you can start another instance +of xterm. The following sections describe how +to open more client windows, place them on the display in +convenient positions, and take advantage of X's networking +capabilities by running clients on other machines. + +To start a client, +at the command-line prompt in any xterm window, +type the name of the client followed by an ampersand () to make the +client run in the background. For example, by typing: + +% oclock + +oclock (analog clock) +you can start a clock application. +The clock will appear in the upper-left quarter of the screen. +With non-rectangular windows like oclock, a titlebar appears to +float above the window. +You can then drag the oclock window to a more convenient location--say +the upper-right corner, as in +Figure 3-14. +(Remember, to move a window, place the pointer on the title area, +press the first button, drag the window outline to the desired +location, and release the button. Notice that the outline is +rectangular, even if the oclock window isn't!) + +
+The oclock window + +
+Though moving windows on the display is fairly simple, manually positioning +every window is not particularly convenient. +For most clients, X provides a way to specify a window's location (and also +its size) automatically--using an option when you run the command. +A window's size and position is referred to as its geometry and +you set these attributes using the option. +The use of this option is discussed in the section “Window Geometry: +Specifying Size and Location,” later in this chapter. + +Unfortunately the developers of oclock neglected to provide an +easy way to remove it. For instructions on removing an oclock +window, see &cmtf08;. +oclock (analog clock)removing +killingclients +windowsremoving + +Command-line Options +clientsoptions +command-line options +optionsclient +-geometry option (X Toolkit) +-display option +command-line options-display +Most X clients accept two powerful and extremely useful options: the + option, which allows you to specify the size and +location of a window on the screen; and the option, +which allows you to specify on which +screen a window should be created. (Most commonly, you'd +use the option to run a client on a remote machine +and display the window locally, that is, on your display.) + +The next few sections illustrate some typical uses of these important +options. In explaining how to use them, we introduce some new, +perhaps somewhat involved concepts (such as the way distances can be +measured on your screen). Bear with us. We feel that you need to master +the and options in order +to begin to take advantage of the powers of X. + +After explaining these options in detail, we'll briefly consider +some of the characteristics you can specify using other common options. + +Window Geometry: Specifying Size and Location +windowsgeometry +windowssize and location +The command-line option to specify a window's size and location has +the form: + +-geometry geometry + +The option can be (and often is) abbreviated as +, unless the client accepts another option that begins +with “g.” + +The parameter to the geometry option (geometry), referred to +as the “standard geometry string,” has four numerical components, +two specifying the window's dimensions and two specifying its +location. The standard geometry string has the syntax: + +widthxheight±xoff±yoff + +Obviously, +the first half of the string provides the width and height +of the window. Many application windows are measured in pixels. +However, application developers are encouraged to use units that are +meaningful in terms of the application. +For example, xterm's dimensions are measured in columns and rows +of font characters. More precisely, an xterm window is some +number of characters wide by some number of lines high (80 characters wide by +24 lines high by default). + +The second half of the geometry string gives the location of the window +relative to the horizontal and vertical edges of the screen. +Imagining the screen to be a grid (where the upper-left corner is 0,0), +xoff (x offset) and yoff (y offset) represent the +x and y coordinates at which the window should be displayed. +The x and y offsets are measured in pixels. + +pixels +Many users may not be accustomed to thinking in terms of pixels. +What exactly is a pixel? A pixel is +the smallest element of a display surface that can be addressed by a +program. You can think of a pixel as one of the tiny dots that make +up a graphic image, such as that displayed by a terminal or a +television. +The number of dots (or pixels) per inch of screen determines the +screen's resolution.The more dots per inch, +the higher the resolution (and, hypothetically, the sharper the picture). + +Hardware manufacturers generally equate resolution with the screen's +overall dimensions in pixels. Thus, you also need to know the actual +physical size of the monitor (in inches) to determine the dots per inch. +We find the dpi figure more useful. + + + +There are other factors that determine the “picture quality” of +a monitor, including “depth,” or the number of bits per pixel. +Depth relates to how many colors a monitor can display. +See “How Many Colors are Available on My Screen?”in &cmtf12;, for more information. + + + +Since a pixel is a tiny unit of measurement, gauging sizes and +distances in pixels will take some practice. +For instance, what are the dimensions of your screen in pixels (its +resolution)? +The xdpyinfo client, described in Chapter 8, will tell you this; +your workstation or X terminal documentation may also provide this information. +xdpyinfo also tells you the screen's resolution in dots per inch. + +Keep in mind that monitors can vary substantially. The Sun 19-inch monitor +has dimensions of 1152 × 900 pixels and a resolution of 90 × 90 dots per inch +(commonly abbreviated to dpi). The NCD 16-inch X terminal has +dimensions of 1024 × 1024 pixels and a resolution of 106 × 106 dpi. + +What are the implications of such hardware differences in specifying +client geometry? +The size and location of client windows is related to +the size and resolution of your screen. +For example, if you specify a window with dimensions of 125 × 125 pixels, +it will appear somewhat larger on the Sun monitor than on the NCD X +terminal. + +So how do we use the geometry option to specify +a window's size and location? +First, be aware that +you can specify any or all elements of the geometry string. +Incomplete geometry specifications are compared to the application's +default settings and missing elements are supplied by these values. +All client windows have a default size. +For example, if you run an xterm window with the geometry +option and specify a location but no +dimensions, the application default size of 80 characters by 24 lines is used. + +If you don't specify the x and y coordinates at which to place a +client window, the client may provide a default location; if the +application doesn't provide a default and mwm is +running, the window manager will automatically position the window in the +upper-left quarter of the screen. + +For now, let's just specify a window's location and let the size be +the application default. +The x and y offsets can be either positive or negative. +If you specify positive offsets, you're positioning the left side +and top side of the window. Negative offsets are interpreted +differently. +The possible values for the x and y offsets and their effects are shown in +Table 3-1. + +Geometry Specification x and y Offsets + +
+For example, the command line: + +% xclock -geometry -10+10 + +places a clock of the default size in the upper-right corner of the +display, 10 pixels from the right and top edges of the screen. + +To place a window in any of the four corners of the screen, flush +against its boundaries, use the following x and y offsets. + + +
+ +If you want a window placed away from one or both edges of the +screen, the guesswork starts. +How many pixels away from the left side of the screen? How many +pixels down from the top? You'll have to experiment with placing some +clients on your screen to get a better idea of x and y offsets. + +It's actually a good idea to start some windows and move them around on +your screen using the pointer. While you're dragging a window, +check the x and y offsets displayed +in the small box mwm places in the center of the screen. +These coordinates are +the positive x and y offsets of the window (i.e., the offsets relative +to the upper-left corner +of the screen). This method for gauging location is fairly reliable. + +There seems to be a very slight delay between +pointer motion and update to the mwm coordinate box. +When you finish dragging the window, the last coordinates visible in the box +may differ from the true coordinates by a pixel in either or both directions. +But this variance is +so trivial that you can supply the coordinates as part of the geometry +string and come very close. + + + +You can also place some windows in different places by dragging and +then determine their geometry specifications +using the xwininfo client, described in &cmtf08;. +Note that when mwm is running, you should +use xwininfo with the option. + +Now what about the size of a window? +For xterm, the size of the window is measured in +characters and lines (by default 80 characters by 24 +lines). If you want to use a large VT100 window, +say 100 characters wide by +30 lines long, you could use this geometry specification: + +% xterm -geometry 100x30-0-0 + +This command creates a large xterm window in the lower-right +corner of the screen, as illustrated by +Figure 3-15. + +
+xterm window sized and positioned with the -geometry option + +
+As stated previously, +most of the standard clients (other than xterm) are measured in +pixels. For example, xclock is 164 pixels square by default +(exclusive of the mwm frame). +A client's default dimensions may appear on its reference page in Part +Three of this guide. However, you'll probably need to experiment with +specifying sizes (as well as locations) on your display. (See +&cmtf08;, and the client reference page, for more about xclock.) + +resource variablesspecifying window size and location +Be aware that the geometry option is not necessarily the only means +available to specify window size and location. +Several clients, including xterm, allow you +to set the size and +location of a window (and often its icon or an alternate window) using +resource variables +variablesresourceresource variables +(in an .Xresources or other defaults file). +We'll introduce some of the basics of specifying +resources later in this chapter. See &cmtf11;, +for more detailed instructions. +See the appropriate +client reference pages in Part Three of +this guide for a complete list +of available resources. + +You should be aware that, as with all user preferences, you may not +always get exactly what you ask for. Clients are designed to work +with a window manager, which may have its own rules for window or icon +size and placement. However, priority is always given to specific +user requests, so you won't often be surprised. +windowsgeometry +windowssize and location +-geometry option (X Toolkit) + + +Running a Client on Another Machine: Specifying the Display +remote systemrunning client on +networkrunning client over +clientsdisplay options +clientsrunning on another machine +clientsoptions +command-line options-display +-display option +DISPLAY environment variable +optionscommand-linecommand-line options +We have yet to take advantage of X's networking capabilities. +Remember that X allows you to run a client on a remote machine across a network. +Generally, the results of a client program are displayed on a screen +connected to the system where the client is running. +However, if you are running a client on a remote system, you probably +want to see the results on your own display (connected to a local server). + +Running a client on a remote machine may give you access to different +software, it may increase the efficiency of certain processes, or +benefit you in a number of other ways. +We discussed some of the advantages of running a +client on a remote machine in &cmtf01;. See the section +“X Architecture Overview” for details. + +But how does running a client on a remote system affect how you work with +the X display? Once a client is running, it doesn't. +You can display the application window +on your own screen, enter input using +your own keyboard and pointer, and read the client's output in the +window on your screen--all while the actual client process occurs on +another machine. + +-display option +In order to run a +client remotely and display its results locally, +you must tell the client process where to display its window. +For this purpose, X provides a command-line option: . +Think of as a pointer to the physical display on +which you want the window to appear. +Like +, the option is recognized by most X +clients. The display option tells the client on which server to +display results (i.e., create its window). The option has the syntax: + + host:server.screen + +The option can be abbreviated as , +unless the client accepts another option that begins with “d.” + +The argument to the option is a three-component +display name. +The host specifies the machine on which to create the window, +the server +specifies the server number, and the screen +specifies the screen number. + +In this context, “host” refers to the Internet address name of the +display hardware. It might be the +name of a single-user workstation, an X terminal, a PC running an X +server, or another hardware device. + +“Server” refers to an instance of the X server program, which controls +a single physical display. +An X display may be composed of multiple screens, but the screens share +one keyboard and pointer. Most workstations have only one keyboard +and pointer and thus are classified as having only one display. +Multiuser systems may have multiple independent displays, each +running a server program. If one display exists, as in the case of +most workstations and X terminals, +it is numbered 0; if a machine +has several displays, each +is assigned a number (beginning with 0) when the X server for that +display is started. + +Similarly, if a single display is composed of multiple screens +(sharing one keyboard and pointer), each +screen is assigned a number (beginning with 0) when the server for that +display is started. Multiple screen displays may be composed of +two or more physical monitors. +Alternatively, two screens might be defined as different ways of using +the same physical monitor. For example, on the Sun-3/60 color workstation, +screen 0 is color, and screen 1 is monochrome. +Each screen is +the size of the monitor; you can only view one screen at a time. +In practice, the two screens seem to be side by side: +you can “scroll” between them by moving the pointer off either +horizontal edge of the screen. + +Note that the server parameter of the display option +always begins with a colon (a double colon after a DECnet +node), and that +the screen parameter always begins with a period. +If the host is omitted or is +specified as unix, the local machine is assumed. +If the screen is omitted, screen 0 is assumed. + +By convention, DECnet node names end with a colon. + + + +Although much of the current X Window System documentation suggests that any of +the parameters to the option can be omitted and will +default to the local node, server and screen 0, respectively, +we have not found this to be true. +In our experience, only the host and screen parameters +(and the period preceding screen) +can be omitted. The colon and server are necessary in +all circumstances. + + +The DISPLAY Environment Variable +DISPLAYenvironment variable +Technically speaking, the option allows you to +override the contents of the DISPLAY environment variable, +displayname +where stored +which stores the display name on UNIX systems. +On UNIX systems, the display name is stored in the DISPLAY +environment variable. +Clients running on the local system access this variable to determine +which physical display to connect to (for most clients, “connecting” +is equivalent to opening a window). +The DISPLAY variable is set +automatically by the xterm terminal emulator. +Thus it is set when you start X and +the first xterm window. + +For most single-user systems, such as workstations, xterm sets +the server and screen numbers to 0, and either omits a +hostname (the local host is assumed) or sets the hostname to “unix,” a generic +name, which also defaults to the local host. If you are working on a +single-user system and run all processes on it, you don't have to deal +with issues concerning the display setting. +Clients running locally access the DISPLAY variable and open +windows on a display connected to the local host. + +If you are using an X terminal, it should already be +configured so that the DISPLAY variable is set properly when +you log on to the local host. Again, if you run all process on the +local machine (to which your terminal is connected), you don't have to +deal with specifying the display. +Clients will access the DISPLAY variable and open windows on +your X terminal screen. + +Complications arise when you want to run a process on a remote machine +and display the results locally. +A client running on a remote machine does not have access to the +DISPLAY variable on the +local machine. By default, a client +running on a remote machine checks the DISPLAY setting on that +machine. + +You can override the DISPLAY environment variable a client +accesses by using the option when you run the command. + + +Using -display +-display optionusing +Say you're using a single display workstation and the display +also has only one screen. The hostname of the workstation is kansas. +In order to tell a client to connect to a display, you must +identify it by its unique name on the network. +(You cannot identify your display by the shorthand setting given to it by +xterm--unix:0.0, :0.0 or some variation.) +Let's assume that the complete display name for the +workstation kansas is: + +kansas:0.0 + +Now let's say you want to run an xterm window on a +faster system--let's call +it oz--on your network. In order to run an xterm on +oz but display the window on your screen connected to +kansas (the local server), you would run the xterm command +using a remote shell +(rsh): +rsh command + +% rsh oz xterm -display kansas:0.0 + + +The command to run the remote process might be different depending +on the available networking software. Ask your system administrator +for the proper command. + + +The xterm process runs on oz, but you've directed +the client to use the display and screen numbered 0 on kansas, +your local system. +Notice that kansas:0.0 is the complete display name. +Hypothetically, if the workstation (kansas) has only one screen +or it has multiple screens but +you want to specify screen 0, you can omit the screen number +and the preceding period (.0). + +Keep in mind that +for this process to succeed, the remote system (oz) must have +permission to “open” the local display (on kansas). +(See “Server Access Control” in &amtfA;, and the xhost +reference page in Part Three of this guide, for more information.) +If oz has not been granted access to the server running on +kansas, the window will not be opened, and you may also get +an error message similar to: +Can't Open displayerror message +error messagesCan't Open display + +Error: Can't Open display + +If your command fails, try entering the command: + +% xhost + + +in an xterm window running on your display. Then run the remote +shell (rsh) again. If problems persist, +consult your system administrator or &bmtf08;. + +The following command illustrates a common mistake: + +% rsh oz xterm + +If you try to run a client using a remote shell and forget to direct the +client to create its window on your own display, the window +will not be displayed and you'll get an error +message stating that the display cannot be opened. + +If you're using an X terminal, it will have a name +unique to the terminal (e.g., ncd8), which should be used +as the host component of the argument. +You should not use the name of the system to which the terminal is +connected. When you run processes on that machine, you don't have to +use . If you want to run a client on another machine +on the network, you must use to point back at your +terminal. + +Say we have a terminal with the full display name: + +ncd8:0.0 + +connected to kansas and we want to run an xterm on +oz. The command: + +% rsh oz xterm -display ncd8:0.0 + +will open the window on our X terminal. + +In addition to specifying a local display, if permissions allow +you can also use the display option to open a window on someone else's +display. +You might want to display a window on another user's screen +for instructional purposes. +Multiuser systems can even be set up to allow teachers to display +educational material simultaneously to +several students, each using an X display of some sort. +And, of course, you might want to display a window on a friend's +screen, just for the fun of it. +(The security problems that allow +both innocent pranks like this, as well as more serious breaches, are +described in &bmtf08;.) + +If you're working on kansas and you want +to open an xterm window on the first display connected to oz, +you could use the command: + +% xterm -display oz:0.0 + +Note that you can only open a window on another display if the +server running that display permits your server access. +(Access must be granted from the remote server, perhaps using xhost.) +If oz does not allow kansas access, this +command will fail and an error message will indicate that the display +cannot be opened. + + +Once You Run a Remote xterm Using -display +A less than obvious repercussion of using to run +a remote xterm is that the option +sets the DISPLAY variable for the new xterm window--and that +DISPLAY setting is passed on to all child processes of the client. +Therefore, once you run an xterm on a remote system and +correctly specify your own display, you can run any number of clients +from that xterm and they will all be displayed on your screen +automatically (no option is necessary). + +In one of the examples in the preceding section, we ran an xterm +on the remote system oz, specifying the local display +kansas:0.0 with the option. +To query the contents of the +DISPLAY variable in the resulting xterm (under the C +shell), use the command: + +% echo $DISPLAY + +The system should echo: + +% kansas:0.0 + +verifying that the display name has been passed to the DISPLAY +variable in the new xterm window. +You can then run any client you want on oz by entering the +command in this xterm window and the window +will automatically be displayed on +kansas:0.0. The DISPLAY setting will also be passed to +any children of this process as well, and will be propagated +for any number of “generations.” + + +Logging In to a Remote System +remote systemlogging in to +DISPLAY environment variablesetting after remote login +rloginsetting DISPLAY +telnetsetting DISPLAY +If you log in to a remote UNIX system using rlogin (or +telnet) in an xterm window, it's a good idea to set the +DISPLAY variable in the new shell to reflect your local +display. Then if you run a client process from this window, the new +window will be placed on your local display and the DISPLAY +setting will be passed on to all child processes. + +When you set the DISPLAY variable from the command +line, the syntax varies depending on the UNIX shell running. The +following command sets the variable under the C shell. + +% setenv DISPLAY kansas:0.0 + +To set the DISPLAY variable under the Bourne shell, use: + +$ DISPLAY=kansas:0.0; export DISPLAY + +DISPLAY environment variable +environment variablesDISPLAY +variablesenvironmentenvironment variables + +Monitoring the Load on a Remote System +remote systemmonitoring load on +load average +A client you may wish to run on another machine is +xload, which is used to keep track of the system load average. +xload (poll system load average) +By default, xload polls the system for the load +average at ten-second intervals and displays the results in a simple +histogram. + +If you are running processes on more than one machine, it's useful to +gauge the level of activity on the systems in question. +This information should help you judge when to start processes and +monitor how your processes are impacting system resources. + +Say you're running clients both on the local machine +kansas and on the remote machine oz. On the local display, +you can have two xload windows, one showing activity on kansas +and another showing activity on oz. + +To create an xload window monitoring activity on kansas, use the +command: + +% xload + +Once the xload window is created, move it to a convenient +location on the screen. + +Then run an xload process on oz using +a remote shell and display the results in a window on +kansas: + +% rsh oz xload -display kansas:0.0 + +The display option tells xload to create its window on the local +display (kansas). +Again, move the window using the pointer. + +Figure 3-16 +shows the resulting kansas display: +two xload windows--the top window monitoring activity on the +local system and the bottom one monitoring activity on the remote system. + +
+Monitoring activity on two systems with xload + +
+clientsstarting additional + +Putting It All Together +Now that we've learned something about the tools of the display, how +to size and position windows, and run remote processes, let's try to +set up a useful working display. + +Say we're using a Sun 3/60 workstation with the hostname +jersey. The workstation has a single display with two screens: +screen 0 is color and screen 1 is black and white. Once X and +the window manager +are running, we might set up the display using the +following commands. + +Note that you should run mwm with the +option to have the program manage all screens on the display. If +you start mwm without this option, it only manages screen 0. In +this case, you can either kill and restart it with + or run another instance of it on screen 1. + + + +First, +run an xterm on a more powerful remote system called +manhattan and place it on screen 0 of jersey. + +% rsh manhattan xterm -geometry +0-0 -display jersey:0.0 +Run xload windows on both jersey and manhattan to +monitor loads on these systems. Again, place the windows +on jersey's color screen in convenient locations. + +% xload -geometry -10-200 + +% rsh manhattan xload -geometry -10-20 -display jersey:0.0 + + +Run another xterm window on jersey. + +% xterm -geometry +50-0 + +Then iconify the login xterm window so that you don't +inadvertently kill it (and shut down X in the bargain). Remember: to +iconify a window place the +pointer on the Minimize command button on the window's frame and click the +first button. (See “Converting a Window to an Icon” earlier in this +chapter.) + +Run an oclock. + +% oclock -geometry +0+0 + +Figure 3-17 +shows the jersey display, screen 0: a fairly useful layout. + +
+A working display, screen 0 + +
+You might also place client windows on the workstation's alternate +screen, the black and white screen numbered 1. +By default, windows are always placed on screen 0 but +you can place a client window on screen 1 +by specifying the screen number in the option when +starting the client. +For instance, +each of the following commands places an xterm window on screen 1. + +% xterm -display jersey:0.1 + +% rsh manhattan xterm -geometry -0-0 -display jersey:0.1 + +Figure 3-18 +illustrates screen 1. + +
+A working display, screen 1 + +
+As we'll see in &amtfA;, on most systems you can place the commands +you run to set up your display in a special file that is invoked when +you log in. Once this file (usually called either .xinitrc or +.xsession) is in place, when you log in your display will be +set up to your specifications automatically. + +Notice that the commands we used to set up jersey illustrate the power of +the and options to create a working +environment that suits individual needs. However, these options +barely hint at the number of features you can specify for each +client. The following section introduces some principles of client +customization. Part Two of this guide examines customization in depth. + +Customizing a Program +command-line options +In a sense, command-line options allow you to customize one program. +We've already seen how to use the and + options, which are accepted by most clients. +&cmtf10;, describes some of the other options accepted by most of +the standard clients. These options set window features such as: + + + +The font in which text is displayed. + + +The background color. + + +The foreground color (such as the color of text). + + +The text displayed in the title area. + + +The text of an icon label. + + +Many clients also accept a large number of +application-specific options (listed on the reference page for each +client in Part Three of this guide). Using a combination of standard and +application-specific options, you can +tailor a client to look and behave in ways that better suit your needs. + +Like most clients, xclock accepts a variety of options. +Some of xclock's options are intended +to enhance the clock display aesthetically and some to +affect its operation. Taking a look at a few of xclock's options +should give you a better idea of the flexibility of X. + +The following command line runs a custom xclock display: + +% xclock -hd green -hl royalblue -bg lightblue -fg royalblue -update 1 -chime + +-hd option +command-line options-hd +-hl option +command-line options-hl +-bg option (X Toolkit) +command-line options-bg (background) +command-line options-fg +-fg option (X Toolkit) +-update option +command-line options-update +As you can see, these specifications are intended for a color monitor. +(X is highly flexible in the use of color. See &cmtf12;, for more +information.) The option sets the color of the clock's +hands to green. The option provides even more +detail, specifying the color of the outline of the hands as royal blue. + and are two of the options accepted by most clients; +they set the window's background and foreground color, in this case to +light blue and royal blue, respectively. + +The option takes as its argument the frequency in +seconds at which the time on the clock should be updated. We've specified +that the time be updated at one second intervals. Thus a second hand +(also green) will be added to the xclock display. +(The xclock reference page in Part Three of this guide specifies +that a second hand is added if is given an argument of +less than 30 seconds.) + +-chime option +The option specifies that the keyboard bell will ring +once on the half hour and twice on the hour. + +These options create a somewhat fancy xclock display. You might +or might not want to use so many options, but these and several more +are available. + +xclock (analog or digital clock) +By default, xclock displays a traditional clock face (an analog clock). +You can create a digital xclock using the following option: + +% xclock -digital + +The digital xclock is pictured in +Figure 3-19. + +
+Digital xclock display + +
+Logically, the and options, which set the color +of the clock hands, are only valid with the analog (default) xclock. +For a complete list of options, see the xclock reference page in +Part Three of this guide. + +Command-line options override the default characteristics of a client +for the single client +process. Traditional UNIX applications rely on command-line options +to allow users to customize the way they work. X also offers many +command-line options, but these options have some limitations and +liabilities. + +First, the number of client features that can be controlled by command +line options is limited. Most applications have many more +customizable features than their command-line options indicate. Actually, +a client can have so many customizable features that typing a command line to +set them all would be impractical. And if you generally use +the same options with a client, it is tedious (and a waste of time) to +type the options each time you run the program. + +clientsspecifying default characteristics for +X offers an alternative to customizing a single client process +on the command line. You can specify default characteristics for a +client using variables called resources. +command-line options + + +Customizing the X Environment +clientscustomizing +customizingclients +X Window Systemenvironment +customizing +customizingX environment +Command-line options allow you to customize one instance of a client +program. In addition, X provides a mechanism that allows you to specify +characteristics that take effect every time you run a client. +Almost every feature of a client program can be controlled using a +variable called a resource. You can change the behavior or +appearance of a program by changing the value associated with a +resource variable. +(In some cases, a resource variable controls the same characteristic as +a command-line option. However, while the option specifies a +characteristic for the single client process being invoked, a resource +variable makes the characteristic the program default.) + +resource variablesfile kept in +.Xdefaults file +.Xresources file +You generally place resource specifications in a file in your home +directory. (The file can have any name, but is often called +.Xresources or .Xdefaults.) +The resources you specify are one of several factors that affect the +appearance and behavior of a client. + +By default, the way a client looks and behaves is determined by +the program code, and in some cases, by +a system-wide file of application defaults. +Several clients have application defaults files that determine certain +client +features. + +For xterm, the application defaults specify such +things as the labels for menu items, the fonts used to display menu items, +and the shape of the pointer when it's in an xterm window. + +Application defaults files generally reside in the +directory /usr/lib/X11/app-defaults and are named for the client +application. +In describing the appearance and behavior of clients in this guide, we +assume all of the standard application defaults files are present on +your system and accessible by the client programs. If, by some chance, +a client's application defaults file has been edited or removed from +your system, the client may not look or behave exactly as we describe it. +If a client application appears substantially different than +depicted in this guide, you may be using a different version of the +program or the application defaults may be different. Consult your +system administrator. + + +Within an application defaults file, defaults are set using resources. +The resources specified in a client's application defaults +files are usually just a subset of a greater number of resources that +can be set. + +If the characteristics you set in your own resources file +already have system-wide application defaults, your own settings +take precedence. +resourcessetting +Keep in mind, however, that command-line options override +both your own defaults and any system-wide defaults for the single +client process. + +To make your resource specifications available to all clients, X +provides a program called xrdb, the X resource database manager. +xrdb stores resources directly in the server where they are +accessible to all clients, regardless of the machine the +clients are running on. + +The basic syntax of a resource specification is fairly simple. Each +client recognizes certain resource variables that can be assigned a +value. The variables for each client are listed on its reference page +in Part Three of this guide. + +A resource definition file is basically +a two-column list, where each line specifies a different resource. +The simplest resource definition line has +the name of the client, followed +by an asterisk, and the name of the variable, followed by a +colon, in the left column. The right column (separated from the left +by a tab or whitespace) contains the value of the resource variable. + +client*variable:value + +The following example shows five simple resource specifications for the +xclock client. These particular resources specify the same +characteristics as the command-line +options we used to create the green and blue xclock in the +preceding section. + + +Resources to create a custom xclock +xclock*hands: green +xclock*highlight: royalblue +xclock*background: lightblue +xclock*foreground: royalblue +xclock*update: 1 +xclock*chime: true + + +To set up your environment so that these characteristics apply each +time you run xclock, you would perform the following steps: + + + +In your home directory, +create a file containing the resources listed in Example 3-1. + +Name the file .Xresources. (A resource file can actually have +any name, but is often called .Xresources or .Xdefaults.) + + +Load the resources into the server by entering the following command +in an xterm window: + +% xrdb -load .Xresources + + + +Then each time you run xclock without options (for the remainder +of that login session), the window will reflect the new defaults. + +You should load resources using xrdb every time you log in. +In &amtfA;, we'll describe how to automate this process using +a special startup script, which also opens the client windows you want +on your display. + +If you want to run an application with different characteristics (colors, +update frequency, etc.) from the defaults, use the appropriate command +line options to override the resource specifications. + +Resource specifications can be much more complicated than our samples +suggest. For applications written with a toolkit (such as the X +Toolkit or the Open Software Foundation's Motif Toolkit), +X allows you to specify different characteristics for individual +components, or widgets, within the application. +Typical widgets create graphical features such as menus, command buttons, +dialog boxes, and scrollbars. Within most toolkit applications is a +fairly complex widget hierarchy--widgets exist within widgets (e.g., a +command button within a dialog box). + +Resource naming syntax can parallel the widget hierarchy within an +application. For instance, you might set different background colors for +different command buttons and specify still another background color +for the dialog box that encloses them. In such cases, the actual widget names +are used within the resource specification. &cmtf11;, +explains the resource +naming syntax in greater detail +and outlines the rules governing the precedence of resources. +It also explains how to use the editres program to examine a +(standard) client's widget hierarchy and set resources accordingly. +X Window Systemenvironment +customizing +customizingX environment +resourcessetting +clientscustomizing +customizingclients + + +Where to Go from Here +There are many useful client programs supplied with the X Window +System. Details of how to use one of the most important +clients, the xterm terminal emulator, are provided in Chapter 5. +Clients to list and display fonts are described in &cmtf06;. +Chapter 6 also describes the X font naming conventions and various +ways to specify fonts on the command line (and in resource files). +Chapter 7 describes several Graphics Utilities available with +X. An overview and tutorial for other standard clients and +instructions on using certain public domain clients +are provided in &cmtf08;. +&cmtf09;, gives instructions on using Motif applications. +All clients are described in detail in a reference +page format in Part Three of this guide. + +We've introduced some basic operations you can perform using the +mwm window manager. +For instructions on performing additional window manager operations, +such as lowering a window, read &cmtf04;. +You can then go on to read more about +xterm in Chapter 5 and about some of the other standard clients +in Chapters 6 through 8. + + diff --git a/docbook/sgml/docbook1.0.dtd b/docbook/sgml/docbook1.0.dtd new file mode 100644 index 000000000..d1ab38156 --- /dev/null +++ b/docbook/sgml/docbook1.0.dtd @@ -0,0 +1,683 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]> + diff --git a/docbook/sgml/docbook1.2.doc.sgml b/docbook/sgml/docbook1.2.doc.sgml new file mode 100644 index 000000000..f1da385e2 --- /dev/null +++ b/docbook/sgml/docbook1.2.doc.sgml @@ -0,0 +1,1094 @@ + +DocBook DTD 1.2: The Elements Alphabetized + +Abstract is a summary of a document's content. It +contains Paras and may bear a Title. Abstract +has common attributes. + +Acronym is a pseudoword made up of the initials or +initial parts of a conventional series of words. For +purposes of the DocBook DTD Acronym may also be a string +of initials. Acronym contains plain text and +has common attributes. + +Action is a function to be invoked in response to a user event. +It contains plain text and has common and HasRefEntry attributes. + +Anchor marks a target for a Link, and may appear almost anywhere. +Anchor has no content, and no end tag. +Anchor has common and Pagenum attributes. + +Appendix may contain anything +found in a Chapter. +It may have a DocInfo and +must have a Title and may have a TitleAbbrev. +Appendix has common and Number attributes. + +Application is the name of a software program that does something +useful. Application may contain +plain text and +has common attributes. + +Author is part of DocInfo and consists of +one or more optional Firstnames and an optional Surname element. +Author also occurs in BiblioEntry. It has +common attributes. + +<AUTHOR><FIRSTNAME>Marmaduke Anthony</FIRSTNAME> +<SURNAME>Pickthall</SURNAME></AUTHOR> + + +AuthorBlurb is a short description of a document's +author. It +contains Paras and may bear a Title. AuthorBlurb +has common attributes. + +AuthorInitials indicate the author of +a Revision or Comment. +AuthorInitials contains plain text and +has common attributes. + +BiblioEntry is an entry in a Bibliography. For +flexibility, it may contain a TitleAbbrev, must +contain at least one of Author, CorpAuthor, OtherAuthor, +Editor, or Title, may +have any or all of +Subtitle, Date, and Publisher, +and following all of that, plain text. BiblioEntry +has common attributes. + +Bibliography may be a book +component on its own, or it may appear within a Preface, Chapter, +or Appendix. It may have a DocInfo, +a Title and a TitleAbbrev, may have one or more introductory Paras, +and contains BiblioEntries. No provision +has been made for bibliographies that are divided into sections. +Bibliography has common attributes. + +BlockQuote is a quotation set off from the main text, +rather than occurring in-line. It may be titled, and +may contain anything found in a Sect except another +Sect---that +is, it may contain Paras, lists, and so forth. BlockQuote has common attributes. + +Book is NOT THE SAME AS DOCBOOK. +A Book is loosely +defined as having a required DocInfo, then an optional ToC, +any number of LoTs, any number of Prefaces, one or more Chapters, +the following: Appnedix, Bibliography, and +then, in order, any number of References, Appendixes, +Glossaries, Bibliographies, and Indexes. +Book has common and Number +attributes (you can supply the number of a Book through +this attribute or as the content of the VolumeNumber +element in DocInfo). + +BookAcronym is an optional part of BookTitle, part of +DocInfo, and +may be used alongside or in preference to TitleAbbrev. +BookAcronym contains plain text and has common attributes. + +BookTitle is part of DocInfo, and contains, in order, +a mandatory Title and optional Subtitle, TitleAbbrev, ReleaseInfo, +and Book Acronym. BookTitle may also appear as the first element +of DocBook. BookTitle has common attributes. + +Button is a button in a graphical user interface. It +contains plain text and has common attributes. + +Caution is an admonition set off from the text and supplied +with a title, which is ``Caution'' unless another Title is +supplied explicitly. The contents of a Caution +may include Paras, lists, and so forth. +Caution has common attributes. + +Chapter may contain anything except +higher-level elements +such as Part, Book, and Set. It may have a DocInfo, +must have a Title, and may have a TitleAbbrev. +Chapter has common and Number attributes. + +Character is a character, that is, an element of a writing +system. Characters may belong to Charsets, and in some contexts +one may speak of fonts as representing characters. But cf. +Glyph, Font. + +Charset is a conventionally defined +set of characters, (not a font). Charset +contains plain text and has common attributes. + +Citation is any in-line bibliographic +reference to another published work that uses a reference +string, such as an abbreviation in a Bibliography. +Citation may contain plain text only, and has +common attributes. + +CiteBook is the name of another book (or journal) +cited in the text. CiteBook may contain in-line elements, +and has common attributes. + +CiteChap is a reference to a specific chapter +(or other component) of any +book cited in the text, including the book in which +the CiteChap appears. CiteChap may contain in-line elements, +and has common attributes. + +CiteRefEntry is a reference to a RefEntry +in any +book cited in the text, including the book in which +the CiteRefEntry +appears. CiteRefEntry may contain in-line elements, +and has common attributes. + +CiteSect is a reference to a specific section of another +document cited in the text, including the document in which +the CiteSect appears. CiteSect may contain in-line elements, +and has common attributes. + +Classname is the name of the class to which a +program component belongs. +Classname contains plain text and has common +and HasRefEntry attributes. + +Command is the name of an executable program, or +the entry a user makes to execute a command. +Command may contain +plain text, FunctionParam, VarParam, Anchor, Optional, +and Option, +and has common and HasRefEntry +attributes. + +Comment is a remark made within the document file that +is intended for use during interim stages of production. A +finished piece of computer documentation intended for an +end user would have no visible Comments. Comment may +appear almost anywhere, and may contain almost anything +below the Section level; +it has common attributes. + +ComputerOutput is data presented to the user by a +computer. It may contain plain text and Anchors, +and has common and HasRefEntry attributes. + +Constant is a fixed value. Constant contains plain text and +has common and HasRefEntry attributes. + +Copyright is part of DocInfo and consists of one or +more Years and any number of Holders. Copyright has common +attributes. + +CorpAuthor is the corporate author of a book, for use +in DocInfo or BiblioEntry. It has common attributes. + +CorpName is the name of a corporation. It contains +plain text and has common attributes. + +Date appears in DocInfo, BiblioEntry, and Revision, and +contains plain text. It has common attributes. No provision +has been made for representing eras; you could include this +information along with the date data. + +DbField is the name of a field in a database. +DBField contains plain text and +has common and HasRefEntry attributes. + +DbName is the name of a database or database file. +DbName contains plain text and +has common and HasRefEntry attributes. + +DbRecord is the name of a record in a database. +DbRecord contains plain text and +has common and HasRefEntry attributes. + +DbTable is the name of a database table. DbTable contains plain text and +has common and HasRefEntry attributes. + +DocBook is the base document element for this DTD. +It is only a wrapper and has no semantic value. + +DocInfo is a book component, containing one or more of the +following: Author, AuthorInitials, BookAcronym, +BookTitle, Copyright, CorpAuthor, CorpName, Date, +Editor, Edition, InvPartNumber, ISBN, LegalNotice, +OrgName, OtherAuthor, PrintHistory, ProductName, ProductNumber, +Publisher, PubsNumber, RevHistory, Series, +and VolumeNumber. No order is enforced among these +elements, but you are urged to begin with BookTitle and Author(s). +DocInfo has common attributes. + +Edition is the edition of a document. It contains +plain text and has common attributes. + +Editor is like Author, an element of DocInfo and +BiblioEntry. It consists of +one or more optional Firstnames and an optional Surname element. +It has common attributes. + +Emphasis is provided for use where one would traditionally employ italics +(more rarely, bold) to emphasize a word or phrase. Emphasis +may contain only plain text; it has common attributes. + +Epigraph is to be used for a brief section of poetry or prose +at the start of a chapter. It contains Paras, and has and +common attributes. + +Equation is a mathematical equation set off on a line +by itself, or occurring in-line. An Equation has an optional +Title and TitleAbbrev, and contains a Graphic, q.v. +Equation has common attributes. + +Error is an error reported by a computer. Error +contains plain text and has common attributes. + +EventStructure is the code that defines an Event. +EventStructure contains plain text and has common and HasRefEntry attributes. + +EventType is a classification of an event. +EventType +contains plain text and has common and HasRefEntry attributes. + +Example is intended for sections of program source code +that are provided as examples in the text. +A Example has an optional Title, +optional TitleAbbrev, and one or more Screens, LiteralLayouts, or +ProgramListings, in any combination. Example has common +attributes and bears the +``linespecific'' Notation attribute. + +ExternalLink is like Link, q.v., except that its +Linkend and Endlink attributes are not defined as +SGML IDREFs; this is so you can make reference to +external documents without +incurring parsing errors. + +Figure is an illustration. A Figure must have a Title, and may have a +TitleAbbrev; it may then contain +one or more of the following: +BlockQuote, Comment, Equation, Example, +FigureFileRef, Graphic, IndexTerm, +LiteralLayout, ProgramListing, Screen, Synopsis, +and Table. +It has an ID attribute, and also +Height, Width, Align, and Float attributes. To +reference an external file containing graphical +content use the Graphic element. + +Filename is the name of a file, including pathname if this +information is present. Filename may contain +plain text, FunctionParam, VarParam, and Anchor, +and has common and HasRefEntry attributes. + +Firstname is part of Author and Editor, q.q.v. It contains +plain text and has common attributes. + +FirstTerm is to be used for the first occurrence +of a word in a given context, when +the style of the document is such that these first occurrences are +differentiated in some manner. A FirstTerm may contain +plain text only, and has common attributes. + +Footnote is the text of a footnote. +The point in the text where the mark for a specific +footnote goes is indicated by FootnoteRef; the text of +the Footnote may appear somewhere else in the file. +A Footnote may contain all of the +permissible contents of Paras. +Footnote has common and Number attributes. + +Font is a collection of Glyphs, q.v. Font +contains plain text and has common attributes. + +FootnoteRef indentifies the location for a footnote mark. +It may contain plain text, which is the mark to be displayed, +or it may be empty. It has ID, Linkend, and Mark +attributes: the Linkend attribute has as its value the ID of +the associated Footnote, and the Mark attribute provides +another way of indicating the contents of the mark (such as an asterisk, *). + +ForeignPhrase is any word or words +from a language other than +that of the document which it is desired to mark off +in some way. In English, inter alia and +c'est la vie are ForeignPhrases. +ForeignPhrase contains plain text and has common attributes. + +Function is a subroutine in a program or external +library. Function may contain +plain text, FunctionParam, VarParam, and Anchor, and +has common and HasRefEntry attributes. + +FunctionParam identifies an argument for a Function. +It may contain plain text, Subscript, and Superscript, +and has common attributes. + +Glossary may occur within a Chapter, Appendix, or Preface, +or may be a book component in its own right. +It contains an optional DocInfo, +optional Title and TitleAbbrev, may contain +any number of Paras, and then consists of GlossaryEntries. +No provision has been made for Glossaries divided into sections. +Glossary has common attributes. + +GlossaryDef is the definition attached to a GlossaryTerm +in a GlossaryEntry, which occurs in a Glossary. It may +contain in-line elements, and has common attributes. + +GlossaryEntry is an entry in a Glossary, containing +a GlossaryTerm and GlossaryDef. Please note that GlossaryEntry occurs +in a Glossary, not in the text of (e.g.) a Chapter +(although a Glossary may be included within a +Chapter). GlossaryEntry +has common attributes. + +GlossaryTerm is an in-line element for tagging terms in the +text of a Chapter (for example) that are glossed in a Glossary, +and also for tagging those terms in GlossaryEntries, in the +Glossary itself. As you may not want to tag all occurrences +of these words outside of Glossaries, you might consider +GlossaryTerm, when used outside of Glossaries, to be similar +to FirstTerm, except that GlossaryTerm may contain other +in-line +elements. GlossaryTerm has common attributes. + +Glyph is a mark, a component of a font. A character +or ligature might be made up of one, two, or more Glyphs. +Glyph contains plain text and has common attributes. +Cf. Character. + +Graphic may occur within a Figure, Table, Screen, +Paragraph, or Equation, to enclose graphical data or to +point to an external file containing the contents of one of these +elements. Graphic contains CDATA (data in which +SGML entities and tags, other than the Graphic end tag, are not +recognized by the SGML parser) and has format, +Fileref, Entityref, and ID attributes. +The format attribute may have the value of +GIF, TIFF, CGM, DVI, EPS, TEX, TBL, EQN, DITROFF, or PS. +If it is desired to point to an external file, a filename may +be supplied as the value of the Fileref attribute, or an +external entity may be supplied as the value of the +Entityref attribute. + +Hardware is any name for a physical part of a computer system. It +may contain plain text, FunctionParam, VarParam, and Anchor, +and has common attributes. + +Highlights is a list of main points that are discussed +a book component such as a Chapter. It may contain +Paras and lists, and has common attributes. + +Holder is part of Copyright and is the name of the +holder of the copyright of the document. It may contain +plain text only, and has common attributes. + +Honorific is a person's title, to be used as part of Author +or Editor. It has common attributes. + +HWapplic describes the hardware to which +given context (such as a RefEntry) is relevant. RefClass is +a good place to put HWapplic information. HWapplic +contains plain text and has common attributes. + +Icon is the name of an icon or image +presented on a computer screen. +Icon contains plaint text and has common attributes. + +Important +is an admonition set off from the text and supplied +with a title, which is ``Important'' unless another Title is +supplied explicitly. The contents of an Important +may include Paras, lists, and so forth. +Important has common attributes. + +Index may occur within a Chapter, Appendix, or +Preface, or may be a book +component on its own. +It contains an optional DocInfo, Title, and TitleAbbrev, may contain +any number of Paras, and then consists of IndexEntries. +No provision has been made for Indices divided into sections. Index has common attributes. + +IndexAs may be nested within the IndexTerm components +Primary, Secondary, and Tertiary to indicate an +alternate string by which the indexed term (the other +content of Primary, Secondary, or Tertiary) should be +indexed in the Index. You might want to use this element +if you tag IndexTerms in the body of the text, rather +than as separate elements. IndexAs contains in-line +elements, and has common attributes. + +IndexEntry is a part of Index, and contains a +PrimaryIE, which may be accompanied by SecondaryIE, +TertiaryIE, SeeIE, and SeeAlsoIE. It has common attributes. + +IndexTerm is a word or phrase to be indexed. +IndexTerm appears in the text, not in the Index; you +can apply IndexTerm +to words in the flow of text or include +IndexTerms as separate elements. +Primary, Secondary, and Tertiary +index items are nested within this tag, as are See and +SeeAlso items. IndexTerm has common, Span, and PageNum + attributes. +The Span attribute, which may have the value +Start or End, may be used for showing a span +of text to be indexed. +The PageNum attribute may be used to +indicate the page on which the indexed term is found in print. + +Interface is the name of any part of a graphical user +interface, +such as a button, icon, menu, menu selection, or window; a more +specific element may be used instead. Interface +plain text, FunctionParam, VarParam, and +Anchor, and has common and HasRefEntry attributes. + +InterfaceDefinition is a specification for a graphical user +interface. It contains plain text and +has common and HasRefEntry attributes. + +InvPartNumber is an inventory part number, which +may occur in DocInfo. It contains plain text and has common attributes. + +ISBN is part of DocInfo, and should be used for the International +Standard Book Number of the document if it has one. (You could use +it for an ISSN, also.) ISBN contains plain text only, and has common attributes. + +ItemizedList is a list in which each item is marked with +a bullet, dash, or other dingbat (or no mark at all). It +consists of one or more ListItems. A ListItem in an +ItemizedList contains Paras and other objects, which +may in turn contain other lists; an ItemizedList may be +nested within other lists, too. ItemizedList +has common attributes and +a Mark attribute. Your application might supply the mark to be used +for an ItemizedList, but you can use this attribute to +indicate the mark you desire to be used (such as +•); for no mark at all, use the attribute but give it +no value. +ItemizedList may be nested within Task, so as to provide a +Title and introductory matter. + +Keycap is the text printed on a physical key on a +computer keyboard, not necessarily the same thing as a +Keycode. Keycap contains plain text and has common and HasRefEntry attributes. + +Keycode is the computer's numeric designation of a key on +a computer keyboard. Keycode contains plain text and has common and HasRefEntry +attributes. + +Keysym is a key symbol name, which is not necessarily the same thing +as a Keycap. The Keysym for the H key (Keycap H) is h, for +example. Keysym contains plain text and has common and HasRefEntry attributes. + +LegalNotice is part of DocInfo, for +acknowledgement of trademarks and so forth. It consists of +Paras and has common attributes. + +LineAnnotation is a writer's or editor's comment on +a line of program code within an Example, ProgramListing, +or Screen. The code's own comments are not +LineAnnotations. LineAnnotation contains plain text +and has common attributes. + +Link is a hypertext link. It may contain in-line elements +and has Endterm, Linkend, and Type attributes. The required +Linkend attribute specifies the target of the link, +and the optional Endterm attribute specifies +text that is to be fetched from elsewhere in the document +to appear in the Link. You can also supply this text directly as +the content of the Link. +The use of the optional Type attribute is undefined, allowing +you to create local link types. + +ListItem is a wrapper for the elements of +item in an ItemizedList or OrderedList; it also +occurs within VarListEntry in VariableList. +It may contain just about anything except Sects and book +components. +ListItem has common attributes. + +Literal is any literal string, used in-line, that is part of +data in a computer. This may be as precise as +the value of an argument, but Literal may also be used +as a catch-all element. Literal may contain plain text +and Anchor; it is not meant as a wrapper for in-line +elements. Literal +has common and HasRefEntry attributes. + +LiteralLayout is the wrapper for lines set off from +the main text that are not tagged as Screens, Examples, +or ProgramListing, in which line breaks and leading +white space are to be regarded as significant. +LiteralLayout +contains in-line elements; it has common attributes +and the ``linespecific'' Notation attribute. + +LoT is the generic tag for such things as a List +of Figures or List of Tables. An LoT may occur within a Chapter, +or Appendix, or may be a book +component on its own. +It contains an optional DocInfo, Title, and TitleAbbrev, +followed by multiple LoTentries. LoT has +common attributes. + +LoTentry is an element of LoT, and contains +the text of the thing to be listed, +including, if desired, in-line elements. LoTentry has +common and PageNum attributes. + +Macro is the name of a computer macro. It contains plain +text and has common attributes. + +ManVolNum, which is specific to UNIX man pages, + designates the section of a complete set of +reference pages that a reference page belongs to. It appears +within RefMeta, contains plain text, and has common +attributes. + +Mask specifies which values in a specified structure should +be read when updating resource values. Mask contains plain text +and has common and HasRefEntry attributes. + +Menu is part of a graphical user interface, containing +choices of actions for the user. Menu contains +plain text and has common and HasRefEntry attributes. + +MenuItem is a choice in a menu. MenuItem contains +plain text and has common and HasRefEntry attributes. + +Note is a message to the user, set off from the text and supplied +with a title, which is ``Note'' unless another Title is +supplied explicitly. The contents of a Note +may include Paras, lists, and so forth. +Note has common attributes. + +Option is a option to a Command (in the Command ``ls -l'' +``-l'' is an Option), but is not nested within Command. It may +contain plain text, FunctionParam, VarParam, and Anchor, and +has common and HasRefEntry attributes. + +Optional is for use in Synopsis, as in a +RefEntry, where optional parameters +conventionally are shown in square +brackets. Optional should replace those brackets; it may contain +any element listed in the parameter +entity computerterms.gp, and has common attributes. + +OrderedList is a numbered or lettered list, consisting of +ListItems. A ListItem in an +OrderedList contains Paras and other objects, which +may in turn contain other lists; an OrderedList may be +nested within +other lists, too. +OrderedList has common attributes, along with +a Numeration attribute, which +may have the value Arabic, Upperalpha, Loweralpha, +Upperroman, or Lowerroman. The default is Arabic. + OrderedList +also has an InheritNum attribute, specifying that for a +nested list the numbering of ListItems should include the +number of the item within which they are nested (2a, 2b, etc., +rather than a, b, etc.). Orderedlist also has +a Continuation attribute, with values Yes or No, +which may be used to +indicate whether the numbering of a list begins afresh (No) +or continues that of the immediately preceding list (Yes). The +default is No, so you need supply the Continuation attribute only +if your list continues the numbering of the preceding list. + +OrgName is the name of an organization that is not +a corporation (cf. CorpName), for use in DocInfo. +It contains plain text +and has common attributes. + +OSname is the name of an operating system. +It contains plain text +and has common attributes. + +OtherAuthor is provided as an alternative to Author and +CorpAuthor. It has common attributes. + +Para is a paragraph. It may have a Title, by means of which +authors may evade the Sect hierarchy, as with a ``bridgehead.'' +Para may contain any in-line element, any list, Graphic, Equation, +Synopsis, Table, BlockQuote, ProgramListing, LiteralLayout, +Screen, and Figure. Abstract, AuthorBlurb, Caution, Important, Note, and +Warning are excluded, as are Sects and higher-level elements. +Para has common attributes. + +Part may be used to compose a Book. It +contains a Title, an optional TitleAbbrev, an optional PartIntro, +followed by two or more Chapters or Appendices. +Part has common and Number attributes. + +PartIntro is a part of Part, and may also appear in +Reference. In Part, it should introduce the +contents of the Part. It may contain just about anything except +Sects. PartIntro has common attributes. + +Preface is a book component, just like a Chapter, +q.v. Use the Title element to provide the word ``Preface'' +or other string as desired. Preface has common attributes. + +Primary is a word or phrase occurring in +the text that is to +appear in the index under as a primary entry. It must be +nested within IndexTerm tags. Primary may contain in-line elements and IndexAs, q.v. Primary. Primary has common and HasRefEntry attributes. + +PrimaryIE is a primary entry in an Index, not in the +text. It may contain only plain text, and has common +attributes and a Linkends attribute, which has the +value of some list of element IDs. + +PrintHistory is part of DocInfo, q.v. It contains Paras +and has common attributes. + +ProductName is a formal name for any product, part +of DocInfo. It contains plain text and has common +attributes. + +ProductNumber is a number assigned to a product, +part of DocInfo. It contains plain text and has common +attributes. + +ProgramListing contains a listing of a program, including +LineAnnotations. +Line breaks and leading +white space are significant in a ProgramListing. Programlisting +may contain in-line elements, and has common attributes. + +Prompt is a prompt appearing on a computer screen, +such as the percent sign (%), +including any other text appearing there (marmaduke%). +Prompt may contain only plain text and has common attributes. + +Property is the name of a defined set of data +associated with a window. Property may contain +in-line elements, and has common attributes. + +ProtocolRequest is a message sent from a program to the +server. ProtocolRequest contains plain text and has common attributes. + +PubsNumber is a number assigned to a publication +other than ISBN, for use +in DocInfo. Cf. also InvPartNumber. PubsNumber +contains plain text and has common attributes. + +Publisher is an element of DocInfo and BiblioEntry. It may contain +plain text only, and has common attributes. + +Quote is supplied for in-line quotations. For block quotes +use BlockQuote. Quote may contain in-line elements and has +common attributes. + +RefClass is an element of RefNameDiv, in which the +applicability or scope of the topic of a RefEntry may be +indicated (such as the element SWapplic or +a string such as ``LocalBlocking''). It may contain +in-line elements and has common attributes. + +RefDescriptor is a substitute for RefName to be used when a +RefEntry covers more than one topic and none of the topic name +is to be used as the sort name. RefDescriptor contains plain +text and has common attributes. + +RefEntry is a reference page. RefEntry +has common attributes. For more on RefEntries see +version 1.0 of the Guide to the DocBook DTD. + +Reference is a collection of RefEntries. It may +be a book +component on its own, +or it may appear within a Preface, Chapter, or Appendix. +Reference has an optional DocInfo, +a required Title, +an optional TitleAbbrev, an optional PartIntro, and +one or more RefEntries. +Reference has common attributes. + +RefFileName is the primary name given to the reference page for +sorting and indexing. It may be the same as the first of +the RefNames, or it may be the same as the +RefDescriptor. +RefFileName may contain only plain text, and has common +attributes. + +RefMeta is the first major division of a reference page, +in which metainformation about the reference page is supplied. +RefMeta is optional, and has common attributes. + +RefMiscInfo marks information in RefMeta that may be +supplied by vendors, such as copyright, release date, revision +date, print status, operating system, hardware architecture, +or a descriptive phrase for use in a print header. It +may contain only plain text, and has common attributes. + +RefName is the name of the subject or subjects of a +reference page, and appears within RefNameDiv. It +may contain plain text and in-line elements, +and has common attributes. + +RefNameDiv is the second major division of a reference page, +in which the name (RefName) or names of the subject or subjects of the +reference page are given, along with a RefPurpose. +RefNameDiv has common attributes. + +RefPurpose is a short phrase describing the subject of +the reference page. It follows the RefNames in +the RefNameDiv division. It may contain in-line elements, +and has common attributes. + +RefSect1 is equivalent to a Sect1 in the DocBook DTD. +It contains a Title, followed by any of the allowable contents +of a Sect, except that only one level of subsection +is allowed, called RefSect2. RefSect1 has common attributes. + +RefSect2 is equivalent to a Sect2 in the DocBook DTD, and may +occur within RefSect1 or RefSynopsisDiv. It may contain any of the +allowable contents of a Sect, except that no further subsections +are allowed. RefSect2 has common attributes. + +RefSynopsisDiv is the third major division of a reference page, +in which the syntax of the subject of the reference page is +indicated. It contains a Synopsis, and may have +subdivisions, which must be RefSect2s, not RefSect1s (that is, +RefSynopsisDiv counts as a RefSect1). +RefSynopsisDiv has common attributes and a Name +attribute, which may be either Synopsis or Syntax; +the default is Synopsis. + +ReleaseInfo is an element of DocInfo, in which +information about a particular version of a document may +occur. It may contain only plain text, and has common attributes. + +Resource is a configurable setting available to a program +that controls its behavior or appearance. +Resource +may contain plain text only, and has common attributes. + +ReturnValue is a value returned by a function. +ReturnValue may contain plain text only, and has common attributes. + +RevHistory is a section of DocInfo +consisting of Revisions. It has common attributes. + +Revision is an entry in RevHistory, describing some +revision made to the text. A Revision has a mandatory +Revisionnumber and Date, one or more sets of AuthorInitials, and a +Revisionremark. It has common attributes. + +RevNumber is an element of Revision, q.v. +It may contain only plain text, and has common +attributes. + +RevRemark is an element +of Revision, describing the Revision. +It may contain only plain text, and has common +attributes. + +Screen is intended to represent what the user sees or +might see on a computer screen. +A Screen may +consist of in-line elements (in which line breaks +and leading white space are considered +significant) or a ScreenInfo and a Graphic. Screen has common attributes and the Notation attribute +``linespecific.'' + +ScreenInfo is a part of Screen, q.v. A ScreenInfo +indicates how the Graphic with which it is paired was created +as a guide for future revisions. It may contain only plain +text, and has common +attributes. + +Secondary is a word or phrase in the text that is to +appear in the index beneath a Primary entry. It must be +nested within IndexTerm tags and must follow a Primary element. +Secondary may contain in-line elements +and IndexAs, and has common and +HasRefEntry attributes. + +SecondaryIE is part of IndexEntry, like PrimaryIE, q.v. + +Sect1 marks a section of a document that +begins with a first-level heading. Anything may occur +within a Sect1 except a DocInfo, Preface, +Chapter, Appendix, or +another Sect1, including a Glossary, Bibliography, RefEntry, Reference, Toc, Index, +or LoT. Sect1 must have a Title, which is the text +of the heading itself, it may have a TitleAbbrev, and must +include some content other than in-line elements and +plain text; these must occur in Paras or other +objects. Sect1--5 have common +and Number attributes. + +Sect2 is a section beginning with a second-level +heading, and must be nested within a Sect1. +Allowable and required content +for Sect2s are like those for Sect1s. + +Sect3. Cf. Sect2. + +Sect4. Cf. Sect2. + +Sect5. Cf. Sect2. No further subdivisions are +supplied in the DocBook DTD. + +See is part of IndexTerm, indicating, for +a word or phrase in the text, the index entry to +which the reader is to be directed when he consults +the stub index entry for another element within +the IndexTerm. +See must be nested within IndexTerm tags and must +follow a Primary or Secondary element. +See may contain in-line +elements and has common and HasRefEntry attributes.. + +SeeAlso is like See, but indicates +the index entries to which the reader is also +to be directed when he consults a full index entry. +SeeAlso must be nested within IndexTerm tags and must +follow a Primary or Secondary element. +SeeAlso may contain in-line +elements and has common and HasRefEntry attributes. + +SeeAlsoIE is a ``see also'' entry in an Index, not in the +text, occurring +unnested within IndexEntry at the PrimaryIE or +SecondaryIE level. +It may contain plain text only, and has common +attributes and a Linkends attribute, which has the +value of some list of IndexEntry IDs. + +SeeIE is a ``see'' entry in an Index, not in the +text, occurring +unnested within IndexEntry at the PrimaryIE or +SecondaryIE level. +It may contain plain text only, and has common +attributes and a Linkend attribute, which has the +value of some IndexEntry ID. + +Seg is a component of a SegmentedList. Segs are the only +content of a SegmentedList's +SegListItems. They may contain in-line +elements. Seg has common and HasRefEntry attributes. + +SegListItem is a list item in a SegmentedList. It consists +of two or more Segs, and has common attributes. + +SegmentedList is a list of sets of units without additional text +(and is thus different from the VarListItem, +composed of Terms and ListItem, +in a VariableList). A SegmentedList may be used to represent +sets of information often presented as simple tables. A SegmentedList +may have a Title and TitleAbbrev, followed by any number +of SegTitles, and two or more SegListItems. SegmentedList +has common attributes. + +SegTitle is a title that pertains to one Seg in each +SegListItem: the first SegTitle to the first Seg, the second SegTitle +to the second Seg, and so on. SegTitles may contain in-line elements, +and are grouped at the beginning of a SegmentedList, before the SegListItems. +SegTitle has common and HasRefEntry attributes. + +Series is part of DocInfo and names the publication series of +which the book is a part. Series may contain only plain text and +has common attributes. + +Set is a set of Books. It has an optional DocInfo and +must contain two or more Books. Set has common attributes. + +Sidebar is a segment of text isolated from the narrative flow +of the main text, typically boxed. A Sidebar may have +a Title and a TitleAbbrev, and must have text formatted in +some fashion: allowable contents +include Paras, lists, Figures, and +Tables. No Sects allowed. Sidebar has common attributes. + +StructField is a field in a Structure. It may +contain plain text only, and has common and HasRefEntry attributes. + +StructName is the name of a Structure. It may +contain plain text only, and has common and HasRefEntry attributes. + +Subscript tags subscripts. It may contain plain text +and another +Subscript, and has common attributes. + +Subtitle is for use in BookTitle. It contains plain text and +has common attributes. + +Superscript tags superscripts. +It may contain plain text and another Superscript, +and has common attributes. + +Surname is an element of Author in DocInfo, supplied so +that a group of documents may be indexed +by their authors's surnames. It may contain +plain text only, and has common attributes. + +SWapplic specifies the applicability of information +given a software context. +RefClass is a good place to put SWapplic information. +SWapplic contains plain text only and has common attributes. + +Symbol is a name that is replaced by a value before processing. +Symbol contains plain text and +has common attributes. + +Synopsis marks the line or lines that provide the +syntax of a command or function. It appears +within RefSynopsisDiv, and may occur elsewhere in +a document, too. +Synopsis may contain in-line elements; within it, +line breaks and white space are significant. It +has common attributes. + +SystemItem may be used for any +system-related item, as a catch-all. +It may contain plain text, FunctionParam, VarParam, +Anchor, and Optional, +and has common and HasRefEntry attributes. + +SystemName is the name of any system. It may +contain plain text only, and has common and HasRefEntry attributes. + +Table is an array of text. A Table may have +a Title, TitleAbbrev, and Graphic; following those +elements +it may have a TableSpec (containing such things as troff +formatting information), any +number of TableColHeads (containing headings +for the columns of the Table), and one or more TableRows of +TableCells. Table has common and Number attributes. + +TableCell is a part of a TableRow in a Table. It may contain +in-line elements and has common attributes. + +TableColHead is an optional part of Table, containing +headings for the columns of the Table as TableCells. +It has common attributes. + +TableRow is part of Table. A Table has TableRows of TableCells. +It has common attributes. + +TableSpec tags formatting information for a Table; it is +not the text of a Table's heading. It may contain +in-line elements and has common attributes. + +Task is any set of Paras and lists that +instructs the reader how to perform a given task. Task +may have a Title and TitleAbbrev, and has common attributes. + +Term is the hanging term attached to a ListItem within +a VarListEntry in a +VariableList; visually, a VariableList +is a set of Terms with attached items such as paragraphs. Each +ListItem may be associated with a set of Terms. Term may contain +in-line elements or Synopsis, and has +common and HasRefEntry attributes. + +Tertiary is a word or phrase that is to +appear in the index under a Secondary entry. It must be +nested within IndexTerm tags and must follow a Secondary element. +Tertiary may contain in-line elements, and has +common and +HasRefEntry attributes. + +TertiaryIE is part of IndexEntry, like PrimaryIE, q.v. + +Tip is a suggestion to the user, set off from the text and supplied +with a title, which is ``Tip'' unless another Title is +supplied explicitly. The contents of a Tip +may include Paras, lists, and so forth. +Tip has common attributes. + +Title is a string of characters, the text of a heading +or element title. It is NOT the title of a Book: that is +BookTitle. Title may contain +in-line elements, and has common and PageNum attributes. + +TitleAbbrev is an optional element of +anything titled. You may want to employ this element when a +title is so long that you fear it will be truncated in +some element of an online display, such as a title bar. +TitleAbbrev may contain +in-line elements, and has common attributes. + +ToC is a Table of Contents, which may be +a book component on its own or may +occur within other book components. It may +have a DocInfo, Title, and TitleAbbrev, +and contains ToCentry1s. ToC has common attributes. + +ToCentry1 is the top-level tag for items in a ToC. In +the manner of +Sect1, it may contain subsidiary groups (e.g., for headings and +subheadings within a chapter), named ToCentry2--5. ToCentry1--5s +have common attributes and +a PageNum attribute, for indicating the page numbers on which +the ToCentries appear in a print book. ToCentry1--5 may contain +in-line elements. + +Token is a unit of information in the context of lexical analysis. + Token contains plain text and +has common and HasRefEntry attributes. + +Type indicates the classification of a value. + Type contains plain text and +has common and HasRefEntry attributes. + +UserInput is an in-line element used to tag data entered by the user. +You might use this element most frequently in LiteralLayouts and +Screens. UserInput may contain in-line elements, and has +common and HasRefEntry attributes. + +VariableList is a list of VarListEntries, which are +composed of sets of one or more Terms with associated +ListItems, which contain Paras. Inclusions +are as for OrderedList, q.v. VariableList has common attributes. + +VarListEntry is a component of VariableList, q.v. + +VarParam tags any character string that is to be +replaced by a real name or value by the user. In +``cat filename,'' filename is a VarParam. If a +VarParam is also, say, a Command, nest the VarParam +tags within the Command tags: VarParam may contain only +plain text, Superscript, and Subscript, +not in-line elements. It has common attributes. + +VolumeNumber is the number of a Book in +relation to a set or Set. It contains plain text +and has common attributes. + +Warning is an admonition set off from the text and supplied +with a title, which is ``Warning'' unless another Title is +supplied explicitly. The contents of a Warning +may include Paras, lists, and so forth. +Warning has common attributes. + +WordAsWord is supplied for use when a word (or letter or +number) is used not to represent the thing or idea it usually +represents, but merely as the word itself. For example, +``The term <WORDASWORD>Gothic</WORDASWORD> means different +things to art historians and typographers,'' or for a single character, +``the +letter <WORDASWORD>X</WORDASWORD>''. WordAsWord may +contain only plain text, and has common attributes. + +XRef is a cross reference link to another part of the document, +such as a Table, Figure, or Example. An XRef +may contain text or be empty; it has an Endterm attribute, the value of which +may be set to the ID of the text to appear in the cross reference if no +content is supplied. +An XRef that has both content and an Endterm attribute is faulty. +XRef also has a Linkend attribute, the value of which is the ID of the +target of the XRef. + +Year is part of DocInfo and BiblioEntry (year of publication of the +book). Year may contain only plain text, and has common attributes. + + + + diff --git a/docbook/sgml/docbook1.2.dtd b/docbook/sgml/docbook1.2.dtd new file mode 100644 index 000000000..fd0509645 --- /dev/null +++ b/docbook/sgml/docbook1.2.dtd @@ -0,0 +1,929 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docbook/sgml/sgml.declaration b/docbook/sgml/sgml.declaration new file mode 100644 index 000000000..81ebfb97f --- /dev/null +++ b/docbook/sgml/sgml.declaration @@ -0,0 +1,66 @@ + diff --git a/docbook/sgml/xlsc.sgm b/docbook/sgml/xlsc.sgm new file mode 100644 index 000000000..0dc8f7542 --- /dev/null +++ b/docbook/sgml/xlsc.sgm @@ -0,0 +1,74 @@ + + +X Window System User's Guide + + + +xlsclients +List Running Clients +xlsclients (list running clients)reference page for +xlsclients +list client applications running on a display. + +xlsclients options + +Description +xlsclients +is a utility for listing information about the client applications +running on a display. It may be used to generate scripts representing +a snapshot of the user's current session. +Note, however, that xlsclients will not list a window manager +process. See &cmtf08;, for more information. + + +Options +xlsclients accepts the following options: + + + + + +Specifies that clients on all screens should be listed. By +default, only those clients on the default screen are listed. + + +host:server[.screen] + +Allows you to specify the display, server, and screen to connect to. +host is the hostname of the physical display, +server specifies the server number, and screen specifies +the screen number. For example, + +% xlsclients -display your_node:0.10 + +specifies screen 1 of server 0 on the display named by your_node. +Either or both the host and screen +can be omitted. If host +is omitted, the local display is assumed. If screen is omitted, +screen 0 is assumed (and the period is unnecessary). +The colon and server are necessary in all cases. + + + + +Requests a long listing showing the window name, icon name, +and class hints in addition to the machine name and command string in +the default listing. + + +max_cmd_length + +Specifies the maximum number of characters in a command to +list. The default is 10000. + + + +See Also +X, xprop, xwininfo; &cmtf08;. + + +Author +Jim Fulton, MIT X Consortium. +xlsclients (list running clients)reference page for + + -- 2.40.0