From 1cad520f3f1d9d520422e3e4d5d8f4ea85a212a4 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Mon, 17 May 2010 20:35:10 -0700 Subject: [PATCH] XFree86 Design doc: Convert LinuxDoc ``quotes'' to DocBook tags Signed-off-by: Alan Coopersmith Tested-by: Gaetan Nadon --- hw/xfree86/doc/sgml/DESIGN.xml | 90 +++++++++++++++++----------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/hw/xfree86/doc/sgml/DESIGN.xml b/hw/xfree86/doc/sgml/DESIGN.xml index 8a3047b40..826a9702c 100644 --- a/hw/xfree86/doc/sgml/DESIGN.xml +++ b/hw/xfree86/doc/sgml/DESIGN.xml @@ -150,7 +150,7 @@ changes: - A &k.device; section is considered ``active'' if there is a reference + A &k.device; section is considered active if there is a reference to it in an active &k.screen; section. @@ -166,7 +166,7 @@ changes: can be used to identify which screen is to be active when multiple &k.screen; sections are present. It is possible to specify the active screen from the command line. A default is chosen in the absence - of one being specified. A &k.screen; section is considered ``active'' + of one being specified. A &k.screen; section is considered active if there is a reference to it either from the command line, or from an active &k.serverlayout; section. @@ -336,7 +336,7 @@ framebuffer code are outside the scope of this document. This approach to the driver interface provides good flexibility, but does increase the complexity of drivers. To help address this, the XFree86 -common layer provides a set of ``helper'' functions to take care of things +common layer provides a set of helper functions to take care of things that most drivers need. These helpers help minimise the amount of code duplication between drivers. The use of helper functions by drivers is however optional, though encouraged. The basic philosophy behind the @@ -466,11 +466,11 @@ mechanism for this. Bus - ``Bus'' is ambiguous as it is used for different things: it may refer + Bus is ambiguous as it is used for different things: it may refer to physical incompatible extension connectors in a computer system. The RAC system knows two such systems: The ISA bus and the PCI bus. (On the software level EISA, MCA and VL buses are currently treated - like ISA buses). ``Bus'' may also refer to logically different + like ISA buses). Bus may also refer to logically different entities on a single bus system which are connected via bridges. A PCI system may have several distinct PCI buses connecting each other by PCI-PCI bridges or to the host CPU by HOST-PCI bridges. @@ -503,7 +503,7 @@ mechanism for this. Resource - ``Resource'' refers to a range of memory or I/O addresses an entity + Resource refers to a range of memory or I/O addresses an entity can decode. @@ -609,7 +609,7 @@ Here is what InitOutput() does: Port I/O access is controlled from the XFree86 common layer, and is - ``all or nothing''. It is enabled prior to calling driver probes, at + all or nothing. It is enabled prior to calling driver probes, at the start of subsequent server generations, and when VT switching back to the Xserver. It is disabled at the end of server generations, and when VT switching away from the Xserver. @@ -775,7 +775,7 @@ Here is what InitOutput() does: calling any driver functions that may access hardware. All generic bus information is probed and saved (for restoration later). All (shared resource) video devices are disabled at the generic bus - level, and a probe is done to find the ``primary'' video device. These + level, and a probe is done to find the primary video device. These devices remain disabled for the next step. @@ -870,7 +870,7 @@ Here is what InitOutput() does: entities. Optionally xf86AllocateScreen() function may also be used to allocate the ScrnInfoRec. Any of these functions take care of initialising fields to defined - ``unused'' values. + unused values. @@ -928,7 +928,7 @@ Here is what InitOutput() does: origIndex, module and drv fields are initialised. The reference count in drv is incremented. The storage for any - currently allocated ``privates'' pointers is also allocated and + currently allocated privates pointers is also allocated and the privates field initialised (the privates data is of course not allocated or initialised). This function never returns on failure. If the allocation fails, the server exits @@ -1107,9 +1107,9 @@ Here is what InitOutput() does: the ScrnInfoRec's driverPrivate field. Any other modules which require persistent data (ie data that persists across server generations) should be initialised in - this function, and they should allocate a ``privates'' index to + this function, and they should allocate a privates index to hook their data into by calling - xf86AllocateScrnInfoPrivateIndex(). The ``privates'' + xf86AllocateScrnInfoPrivateIndex(). The privates data is persistent. @@ -1406,18 +1406,18 @@ Here is what InitOutput() does: - A resource marked ``disabled'' during OPERATING state will be + A resource marked disabled during OPERATING state will be ignored entirely. - A resource marked ``unused'' will only conflict with an overlapping + A resource marked unused will only conflict with an overlapping resource of an other entity if the second is actually in use during OPERATING state. - If an ``unused'' resource was found to conflict but the entity + If an unused resource was found to conflict but the entity does not use any other resource of this type the entire resource type will be disabled for that entity. @@ -1619,7 +1619,7 @@ Here is what InitOutput() does: -1, -1, -1, -1, -1, NewApertureAddress);
- where the ``ppix'' field in a ScrnInfoRec + where the ppix field in a ScrnInfoRec points to the pixmap used by the screen's SaveRestoreImage() function to hold the screen's contents while switched out. @@ -1759,7 +1759,7 @@ MODECHECK_FINAL are intended for checks that may involve more than one mode. call. This would predominantly be data allocated by ChipPreInit() that persists across server generations. It would include the driverPrivate, - and any ``privates'' entries that modules may have allocated. + and any privates entries that modules may have allocated.
@@ -2279,8 +2279,8 @@ these and will disable them before returning from PreInit(). This also applies to all other driver functions. Several functions are provided to request resource ranges, register these, correct PCI config space and add replacements for the -generic access functions. Resources may be marked ``disabled'' or -``unused'' during OPERATING stage. Although these steps could also be +generic access functions. Resources may be marked disabled or +unused during OPERATING stage. Although these steps could also be performed in ScreenInit(), this is not desirable. @@ -2311,18 +2311,18 @@ rules: - A resource marked ``disabled'' during OPERATING state will be ignored + A resource marked disabled during OPERATING state will be ignored entirely. - A resource marked ``unused'' will only conflicts with an overlapping + A resource marked unused will only conflicts with an overlapping resource of an other entity if the second is actually in use during OPERATING state. - If an ``unused'' resource was found to conflict however the entity + If an unused resource was found to conflict however the entity does not use any other resource of this type the entire resource type will be disabled for that entity. @@ -2357,7 +2357,7 @@ certain resources: driver function enabling them needs to disable them before it will return. This should be used if a resource which can be controlled in a device dependent way is only required during SETUP state. This - way it can be marked ``unused'' during OPERATING state. + way it can be marked unused during OPERATING state. @@ -2602,8 +2602,8 @@ available at the driver level: Takes a BusID string, and if it is in the correct format, returns the PCI bus, device, func values that it indicates. The format of the - string is expected to be "PCI:bus:device:func" where each of `bus', - `device' and `func' are decimal integers. The ":func" part may + string is expected to be "PCI:bus:device:func" where each of bus, + device and func are decimal integers. The ":func" part may be omitted, and the func value assumed to be zero, but this isn't encouraged. The "PCI" prefix may also be omitted. The prefix "AGP" is currently equivalent to the "PCI" prefix. If the string @@ -3147,7 +3147,7 @@ The flags are ORed together. - Config file ``Option'' entries + Config file <quote>Option</quote> entries Option entries are permitted in most sections and subsections of the @@ -3520,7 +3520,7 @@ Next, the higher level functions that most drivers would use.
This function should be used when comparing strings from the config file with expected values. It works like strcmp(), - but is not case sensitive and space, tab, and `_' characters + but is not case sensitive and space, tab, and _ characters are ignored in the comparison. The use of this function isn't restricted to parsing option values. It may be used anywhere where this functionality required. @@ -4498,7 +4498,7 @@ typedef struct { XFree86 offers the X Video Extension which allows clients to treat video -as any another primitive and ``Put'' video into drawables. By default, +as any another primitive and Put video into drawables. By default, the extension reports no video adaptors as being available since the DDX layer has not been initialized. The driver can initialize the DDX layer by filling out one or more XF86VideoAdaptorRecs @@ -4606,12 +4606,12 @@ as follows: VIDEO_NO_CLIPPING This indicates that the video adaptor does not support - clipping. The driver will never receive ``Put'' requests + clipping. The driver will never receive Put requests where less than the entire area determined by drw_x, drw_y, drw_w and drw_h is visible. - This flag does not apply to ``Get'' requests. Hardware - that is incapable of clipping ``Gets'' may punt or get + This flag does not apply to Get requests. Hardware + that is incapable of clipping Gets may punt or get the extents of the clipping region passed to it. @@ -4817,7 +4817,7 @@ as follows: the various hardware expected to be used with this extension, it is not expected that all hardware will be able to do this exactly as described. In that case the driver should just do - ``the best it can,'' scaling as closely to the target rectangle + the best it can, scaling as closely to the target rectangle as it can without rendering outside of it. In the worst case, the driver can opt to just not turn on the video. @@ -5065,7 +5065,7 @@ typedef struct { Each adaptor may have an array of these advertising the attributes for its ports. Currently defined flags are XvGettable and XvSettable which may be OR'd together indicating that - attribute is ``gettable'' or ``settable'' by the client. The + attribute is gettable or settable by the client. The min and max field specify the valid range for the value. Name is a text string describing the attribute by name. @@ -5385,7 +5385,7 @@ XFree86 common layer. - When loading ``external'' modules (modules that don't + When loading external modules (modules that don't have the standard entry point, for example a special shared library) the options parameter can be set to EXTERN_MODULE to tell the @@ -5423,7 +5423,7 @@ typedef struct { information in the module's XF86ModuleVersionInfo record (which is described below). The values in comments above - indicate ``don't care'' settings for each of the fields. + indicate don't care settings for each of the fields. The comparisons made are as follows: @@ -5968,12 +5968,12 @@ the server, and may also be used from within modules. int errmaj, int errmin);
- This function prints an error message that includes the text ``Failed - to load module'', the module name modname, a message + This function prints an error message that includes the text Failed + to load module, the module name modname, a message specific to the errmaj value, and the value if errmin. If name is non-NULL, it is printed as an identifying prefix - to the message (followed by a `:'). + to the message (followed by a :).
@@ -6036,9 +6036,9 @@ typedef struct { Helper Functions -This section describe ``helper'' functions that video driver +This section describe helper functions that video driver might find useful. While video drivers are not required to use any of -these to be considered ``compliant'', the use of appropriate helpers is +these to be considered compliant, the use of appropriate helpers is strongly encouraged to improve the consistency of driver behaviour. @@ -6994,7 +6994,7 @@ be catered for the by the helpers. Note that the mode->SynthClock field is always filled in by xf86ValidateModes(): it will contain - the ``data transport clock'', which is the clock that will have + the data transport clock, which is the clock that will have to be programmed in the chip when it has a programmable clock, or the clock that will be picked from the clocks list when it is not a programmable one. Thus: @@ -7975,7 +7975,7 @@ programming the standard VGA registers, and for handling VGA colourmaps. void writeMiscOut(vgaHWPtr hwp, CARD8 value);
- Write `value' to the Miscellaneous Output register. + Write value to the Miscellaneous Output register.
@@ -8112,7 +8112,7 @@ most drivers (even those which don't fit that basic description). The information here is based on the initial conversion of the Matrox -Millennium driver to the ``new design''. For a fleshing out and sample +Millennium driver to the new design. For a fleshing out and sample implementation of some of the bits outlined here, refer to that driver. Note that this is an example only. The approach used here will not be appropriate for all drivers. @@ -8122,7 +8122,7 @@ appropriate for all drivers. Each driver must reserve a unique driver name, and a string that is used to prefix all of its externally visible symbols. This is to avoid name space clashes when loading multiple drivers. The examples here are for -the ``ZZZ'' driver, which uses the ``ZZZ'' or ``zzz'' prefix for its externally +the ZZZ driver, which uses the ZZZ or zzz prefix for its externally visible symbols. @@ -8373,7 +8373,7 @@ typedef struct { Define the list of config file Options that the driver accepts. For - consistency between drivers those in the list of ``standard'' options + consistency between drivers those in the list of standard options should be used where appropriate before inventing new options.