#AutoTag

This command allows you to automatically modify text. This is mainly handly when "#AsIs" mode is on and you are including text which you don't wish to modify (such as a real live working module you wish to use as an example).

By default the search operation is case sensitive and a simple textual replacement occurs. There are other options such as case insensitive replacements that you can set using the AtChangeType option.

When used with the "#AsIs" command you can include real working code as examples and link parts of this working example to your explanations.

Automatic tagging is not recommended for general use as it can greatly decrease performance of this program and you may of course have unexpected replacements occur.

AutoTag definitions are applied to lines in the order of declaration in a single pass. This means that you can make use of common "macro" like tags but they must be defined later than all references. If AutoTags are used while "#AsIs" mode is off then it can generate references to #define variables and they will be expanded.

You can temporarily hide or extend the existing autotag list with the "#AutoTagState" command. You can clear all or some AutoTags with "#AutoTagClear".

Only lines that come directly from a file are tagged. Macro contents are safe. Autotagging occurs after any required "#AsIs" tagging.

The parameters shown below do not have macros expanded before this command processes them. This ensures that complex macros can be handled. The replacement will occur after the autotag text has been replaced.

Syntax #1 - Turn it ON or OFF

[WhiteSpace]#AutoTag  ["]OnOrOffCommand["]

This form of the command turns on or off the automatic tagging of text. The "OnOrOffCommand" parameter should be "+", "ON" or "YES" to keep leading whitespace otherwise use "-", "OFF" or "NO".

Syntax #2 - Define {SelfReferenceCode}

[WhiteSpace]#AutoTag  SELFREF [ ["]ReplaceMeText["] ]

When you refine a tag to be replaced the "before" text can be included in the "after" text by marking where it should be replaced. The marker is case sensitive.

The default marker is "{$AT}" (set once at startup) which works well except that it will fail if this command is used inside of a macro. It remains the default for backwards compatibility (not because it was a good idea).

If the "ReplaceMeText" parameter is "" then the default marker is set otherwise your chosen one will be used.

Syntax #3

[WhiteSpace]#AutoTag  ["]BeforeText["] [ ["]AfterText["]  [#Slot]]

The "BeforeText" is translated into "AfterText". Note that the "AfterText" can contain the "BeforeText" and both can contain absolutely any characters. If the "AfterText" parameter is missing (not empty) then the first autotag for "BeforeText" is deleted. Note that "AfterText" can contain the string "{$AT}" which will get replaced with the value of "BeforeText". Macros within the "BeforeText" are never replaced.

The optional "Slot" parameter can be used to adjust the ordering of the tag. Normally the new tag is placed after all existing ones, to make it first specify "#1". A tag of "#2" would ensure its the second change etc.

The AutoTagAdd() routine is another way to define replacements.

Note that its perfectly legal and in some cases may be required that you specify the same "BeforeText" more than once.

When "#AsIs" mode is on you need to be very careful about what you use as replacement text, for example if you wish to see a '<' character you will actually need to use '&lt;' instead!

Example

In the following example we are including "C:\AUTOEXEC.BAT" and wish to create hypertext links from the "REM" command to "rem.htm" and from the "SET" command to "set.htm".

Note that I expect my source to contain "set" or "SET" but not "SeT" etc (note you can set it up to handle all cases). To eliminate the chance (in this example certainty) of clashes with future #autotag commands, I used the text "<?_>" to split up the first #autotag involving the "set" command (this way the following autotag won't "improve" on the changes made by the one above).

Also note that I look for "SET" and not "SET ", this is silly as it would also match on "SETTLE" or other similar text and not just "SET" commands which I know needs at least one space.

#AutoTag  SelfRef   "{*}"
#AutoTagClear
#AutoTag  "REM "    '<A HREF="rem.htm">REM</A> '
#AutoTag  /SET/    *<A HREF="s<?_>et.htm">{*}</A>*
#AutoTag  "set"    ~<A HREF="set.htm">set</A>~
#AutoTag  ON
<$IncludeExampleFile FILE="C:\AUTOEXEC.BAT" TEXT='Example file "C:\AUTOEXEC.BAT"'>
#AutoTag  OFF

email me  any feedback, additional information or corrections.
See this page online (look for updates)

PPWIZARD Manual

Saturday May 28 2022 at 2:55pm