Changes between Initial Version and Version 1 of HemlockUser/ManagingLargeSystems


Ignore:
Timestamp:
11/05/07 17:09:30 (7 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockUser/ManagingLargeSystems

    v1 v1  
     1[[PageOutline]] 
     2 
     3= 5 Managing Large Systems = 
     4 
     5Hemlock provides three tools which help to manage large systems: 
     6 
     7 1. File groups, which provide several commands that operate on all 
     8 the files in a possibly large collection, instead of merely on a 
     9 single buffer. 
     10 
     11 2. A source comparison facility with semi-automatic merging, which 
     12 can be used to compare and merge divergent versions of a source 
     13 file. 
     14 
     15 3. A change log facility, which maintains a single file containing a 
     16 record of the edits done on a system. 
     17 
     18== 5.1 File Groups == 
     19 
     20A file group is a set of files, upon which various editing operations 
     21can be performed. The files in a group are specified by a file in the 
     22following format: 
     23 
     24 * Any line which begins with one "@" is ignored. 
     25 
     26 * Any line which does not begin with an "@" is the name of a file in 
     27   the group. 
     28 
     29 * A line which begins with "@@" specifies another file having this 
     30   syntax, which is recursively examined to find more files in the 
     31   group. 
     32 
     33This syntax is used for historical reasons. Although any number of 
     34file groups may be read into Hemlock, there is only one active group, 
     35which is the file group implicitly used by all of the file group 
     36commands. Page 9.5 describes the Compile Group command. 
     37 
     38Select Group             [Command] 
     39 
     40This command prompts for the name of a file group to make the active 
     41group. If the name entered is not the name of a group whose definition 
     42has been read, then the user is prompted for the name of a file to 
     43read the group definition from. The name of the default pathname is 
     44the name of the group, and the type is "upd". 
     45 
     46 
     47 
     48Group Query Replace              [Command] 
     49 
     50This command prompts for target and replacement strings and then 
     51executes an interactive string replace on each file in the active 
     52group. This reads in each file as if Find File were used and processes 
     53it as if Query Replace were executing. 
     54 
     55 
     56 
     57Group Replace            [Command] 
     58 
     59This is like Group Query Replace except that it executes a 
     60non-interactive replacement, similar to Replace String. 
     61 
     62 
     63 
     64Group Search             [Command] 
     65 
     66This command prompts for a string and then searches for it in each 
     67file in the active group. This reads in each file as if Find File were 
     68used. When it finds an occurrence, it prompts the user for a key-event 
     69indicating what action to take. The following commands are defined: 
     70 
     71 Escape, Space, y:: 
     72  Exit Group Search. 
     73 
     74 Delete, Backspace, n:: 
     75  Continue searching for the next occurrence of the string. 
     76 
     77 !:: 
     78  Continue the search at the beginning of the next file, skipping the 
     79  remainder of the current file. 
     80 
     81 C-r:: 
     82  Go into a recursive edit at the current location, and continue the 
     83  search when it is exited. 
     84 
     85 
     86Group Find File         (initial value nil)      [Variable] 
     87 
     88The group searching and replacing commands read each file into its own 
     89buffer using Find File. Since this may result in large amounts of 
     90memory being consumed by unwanted buffers, this variable controls 
     91whether to delete the buffer after processing it. When this variable 
     92is false, the default, the commands delete the buffer if it did not 
     93previously exist; however, regardless of this variable, if the user 
     94leaves the buffer modified, the commands will not delete it. 
     95 
     96 
     97Group Save File Confirm         (initial value t)        [Variable] 
     98 
     99If this variable is true, the group searching and replacing commands 
     100ask for confirmation before saving any modified file. The commands 
     101attempt to save each file processed before going on to the next one in 
     102the group. 
     103 
     104 
     105== 5.2 Source Comparison == 
     106 
     107These commands can be used to find exactly how the text in two buffers 
     108differs, and to generate a new version that combines features of both 
     109versions. 
     110 
     111Source Compare Default Destination      (initial value "Differences")    [Variable] 
     112 
     113This is a sticky default buffer name to offer when comparison commands 
     114prompt for a buffer in which to insert the results. 
     115 
     116 
     117 
     118Compare Buffers                  [Command] 
     119 
     120This command prompts for three buffers and then does a buffer 
     121comparison. The first two buffers must exist, as they are the buffers 
     122to be compared. The last buffer, which is created if it does not 
     123exist, is the buffer to which output is directed. The output buffer is 
     124selected during the comparison so that its progress can be 
     125monitored. There are various variables that control exactly how the 
     126comparison is done. 
     127 
     128If a prefix argument is specified, then only only the lines in the the 
     129regions of the two buffers are compared. 
     130 
     131 
     132Buffer Changes                   [Command] 
     133 
     134This command compares the contents of the current buffer with the disk 
     135version of the associated file. It reads the file into the buffer 
     136Buffer Changes File, and generates the comparison in the buffer Buffer 
     137Changes Result. As with Compare Buffers, the output buffer is 
     138displayed in the current window. 
     139 
     140 
     141Merge Buffers            [Command] 
     142 
     143This command functions in a very similar fashion to Compare Buffers, 
     144the difference being that a version which is a combination of the two 
     145buffers being compared is generated in the output buffer. This copies 
     146text that is identical in the two comparison buffers to the output 
     147buffer. When it encounters a difference, it displays the two differing 
     148sections in the output buffer and prompts the user for a key-event 
     149indicating what action to take. The following commands are defined: 
     150 
     151 
     152 1:: 
     153  Use the first version of the text. 
     154 
     155 2:: 
     156  Use the second version. 
     157 
     158 b:: 
     159  Insert the string "**** MERGE LOSSAGE ****" followed by both 
     160  versions. This is useful if the differing sections are too complex, 
     161  or it is unclear which is the correct version. If you cannot make 
     162  the decision conveniently at this point, you can later search for 
     163  the marking string above. 
     164 
     165 C-r:: 
     166  Do a recursive edit and ask again when the edit is exited. 
     167 
     168 
     169Source Compare Ignore Case      (initial value nil)      [Variable] 
     170 
     171If this variable is non-nil, Compare Buffers and Merge Buffers will do 
     172comparisons case-insensitively. 
     173 
     174 
     175 
     176Source Compare Ignore Indentation       (initial value nil)      [Variable] 
     177 
     178If this variable is non-nil, Compare Buffers and Merge Buffers ignore 
     179initial whitespace when comparing lines. 
     180 
     181 
     182 
     183Source Compare Ignore Extra Newlines    (initial value t)        [Variable] 
     184 
     185If this variable is true, Compare Buffers and Merge Buffers will treat 
     186all groups of newlines as if they were a single newline. 
     187 
     188 
     189 
     190Source Compare Number of Lines          (initial value 3)        [Variable] 
     191 
     192This variable controls the number of lines Compare Buffers and Merge 
     193Buffers will compare when resynchronizing after a difference has been 
     194encountered. 
     195 
     196== 5.3 Change Logs == 
     197 
     198The Hemlock change log facility encourages the recording of changes to 
     199a system by making it easy to do so. The change log is kept in a 
     200separate file so that it doesn't clutter up the source code. The name 
     201of the log for a file is specified by the Log file option (see page 
     2023.3.3.) 
     203 
     204Log Change               [Command] 
     205 
     206Log Entry Template      (initial value )         [Variable] 
     207 
     208Log Change makes a new entry in the change log associated with the 
     209file. Any changes in the current buffer are saved, and the associated 
     210log file is read into its own buffer. The name of the log file is 
     211determined by merging the name specified in the Log option with the 
     212current buffer's file name, so it is not usually necessary to put the 
     213full name there. After inserting a template for the log entry at the 
     214beginning of the buffer, the command enters a recursive edit (see 
     215section 1.13) so that the text of the entry may be filled in. When the 
     216user exits the recursive edit, the log file is saved. 
     217 
     218The variable Log Entry Template determines the format of the change 
     219log entry. Its value is a Common Lisp format control string. The 
     220format string is passed three string arguments: the full name of the 
     221file, the creation date for the file and the name of the file 
     222author. If the creation date is not available, the current date is 
     223used. If the author is not available then nil is passed. If there is 
     224an @ in the template, then it is deleted and the point is left at that 
     225position. 
     226