Moderators: Dorian (MJT support), JRL
Code: Select all
LabelToVar>test_string,test_string,1,1,*/
RegEx>(?<!\\)[&%$#\{\}~^],test_string,0,,,1,\<match>,test_string_2
/*
test_string:
this number: #1
this ampersand: &
this percent: %
*/
Code: Select all
this number: #1
this ampersand: &
this percent: %
Code: Select all
this number: \1
this ampersand: \
this percent: \
Code: Select all
this number: \#1
this ampersand: &
this percent: \%
Code: Select all
this number: \\#1
this ampersand: \&
this percent: \\%
Code: Select all
LabelToVar>test_string,test_string,1,1,*/
RegEx>(?<!\\)[&%$#\{\}~^],test_string,0,,,1,\test,test_string_2
RegEx>(?<!\\)[&%$#\{\}~^],test_string,0,,,1,\\test,test_string_3
RegEx>(?<!\\)[&%$#\{\}~^],test_string,0,,,1,\r,test_string_4
RegEx>(?<!\\)[&%$#\{\}~^],test_string,0,,,1,{$110},test_string_5
/*
test_string:
this number: #1
this ampersand: &
this percent: %
*/
Code: Select all
this number: est1
this ampersand: est
this percent: est
Code: Select all
this number: \test1
this ampersand: \test
this percent: \test
Code: Select all
this number:
1
this ampersand:
this percent:
Code: Select all
this number: 2721
this ampersand: 272
this percent: 272
Code: Select all
LabelToVar>test_string,test_string,1,1,*/
RegEx>(?<!\\)([&%$#\{\}~^]),test_string,0,,,1,\\$1,test_string_2
MDL>test_string_2
/*
test_string:
this number: #1
this ampersand: &
this percent: %
*/
Code: Select all
this number: \#1
this ampersand: \&
this percent: \%
Code: Select all
LabelToVar>text_string,text_string,1,1,*/
RegEx>(Grovkillen|Allan)(!),text_string,0,,,1,$1..ABC123..$2,text_string_2
MDL>text_string_2
/*
text_string:
Are you Allan?
Allan!? My name is Grovkillen!
Aha, Grovkillen... got ya!
*/
Code: Select all
Are you Allan?
Allan..ABC123..!? My name is Grovkillen..ABC123..!
Aha, Grovkillen... got ya!
Code: Select all
<HTML><HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=windows-1252">
<TITLE>How to Write a Great Help File</TITLE>
<OBJECT TYPE="application/x-oleobject" CLASSID="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
<PARAM NAME="Keyword" VALUE="how to">
</OBJECT>
<META NAME="AUTHOR" CONTENT="Copyright © 1996-2003 Jan Goyvaerts">
<META NAME="GENERATOR" CONTENT="HelpScribble 7.9.0">
<STYLE> span { display: inline-block; }</STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>How to Write a Great Help File</B></FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" COLOR="#800000" SIZE="2"><HR></FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">A lot of software these days ships with help files of very questionable quality. Even help files included with expensive software from big companies often leave a lot to be desired.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">Just what is a great help file? It's simple: a great help file is a help file that provides the user with exactly that information which the user needs at any time while requiring a minimum amount of effort to locate that information.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">An obvious requirement that follows from our definition of a great help file is that every aspect of the software must be documented, because you cannot know in advance which aspect of the software a particular user may want help with. However, unless your software is very limited in functionality, documenting every little detail will make it more difficult for novice users to see the forest through the trees.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">Therefore, a great help file consists of two main sections. The first section is a "how to" section that explains the basic tasks of the software. It focuses on how to get something done with the software, rather than trying to explain everything. Information is presented in a logical order with respect to the user's work flow, possibly using step by step instructions. The second section is the reference section that explains each and every detail of the software. It focuses on explaining what each part of the software can be used for.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="3"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">People new to the software will mostly read the "how to" section, while expert users will look up the information they want in the reference section. However, most people using the software will actually be neither beginner nor expert, but something in between. Therefore, both sections should </FONT><FONT FACE="Arial" SIZE="2"><A HREF="hs1000.htm#howtolink">link</A></FONT><FONT FACE="Arial" SIZE="2"> to each other. Whenever the "how to" section mentions a feature, that mention should be a link to the reference section. As the user gains more experience, she can easily find information in the reference section by using the "how to" topic she is already familiar with as a starting point. In the reference section, topics explaining the details of a certain part of the software should link to the relevant "how to" topics. Somebody new to the software may wonder what a certain command is for, and arrive in the reference section via the </FONT><FONT FACE="Arial" SIZE="2"><A HREF="hs1100.htm">index</A></FONT><FONT FACE="Arial" SIZE="2">, while a basic "how to" text would be more interesting for that person at that time.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="1"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">Speaking of links: a great help file can never have enough links. Whenever you mention a feature or concept that is explained elsewhere, make that mention a link so the user can easily get more information. Remember that help files are not read cover to cover. They don't have covers. Rather, people will read a few </FONT><FONT FACE="Arial" SIZE="2"><A HREF="hs1000.htm">topics</A></FONT><FONT FACE="Arial" SIZE="2"> when they get stuck with the software. So you cannot assume anything about what the customer already knows and what not.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">Another important and related fact is that most readers will arrive at a certain topic "out of nowhere". Maybe they found the topic through the </FONT><FONT FACE="Arial" SIZE="2"><A HREF="hs1100.htm">index</A></FONT><FONT FACE="Arial" SIZE="2"> or they clicked on a link without really knowing what to expect. Therefore, every topic must establish a context. If a topic explains a certain menu item, like </FONT><FONT FACE="Arial" SIZE="2">Project|Save</FONT><FONT FACE="Arial" SIZE="2">, that topic must first mention that it is talking about a menu item, and where that menu can be found. If I look up "save project" in the index, and I get a topic that only says "click this button to save your project", then I have learned absolutely nothing. I want to know <I>where</I> that button is. It seems that a lot of technical writers did not fully grasp this yet. A help file is not a book. I cannot flip back a few pages to establish the context. In WinHelp, browse sequences can simulate "page flipping". But a link to the </FONT><FONT FACE="Arial" SIZE="2">Project menu</FONT><FONT FACE="Arial" SIZE="2"> from the </FONT><FONT FACE="Arial" SIZE="2">Save</FONT><FONT FACE="Arial" SIZE="2"> topic is just so much easier than clicking the </FONT><FONT FACE="Courier" SIZE="2"><<<</FONT><FONT FACE="Arial" SIZE="2"> button three times and then guessing I may find the Save item in the Project menu.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">I have already mentioned the use of the index several times. A great help file must have a comprehensive index. Make sure that each topic is included in the index, with every synonym you can think of, an with every possible permutation of multi-word concepts. See </FONT><FONT FACE="Arial" SIZE="2"><A HREF="hs1100.htm">How to Add an Index</A></FONT><FONT FACE="Arial" SIZE="2"> for more information.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" COLOR="#008000" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"><A HREF="hs1300.htm">Screen shots</A></FONT><FONT FACE="Arial" SIZE="2"> are also an important part of a help file. Usually the software will be hidden behind the help window. Looking at the screen shot in the help file while reading the help text is easier than task-switching back and forth between the application and the help file. Seeing a screen shot that is identical to the actual software also assures the user that the help file is accurate. So when you add screen shots, it is very important to update them as the software gets updated. When a screen shot differs from the actual software, the user will not trust the help text.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">If your help file is distributed with a free evaluation version of the software, the quality of your help file will definitely influence people's decision whether to buy this software or a competing product. Though many people will hardly use your help file at all, most will take a look at it to check if solid documentation is available, should they ever get stuck with the software. It is also far easier to verify the quality of a help file than the quality of an application. Anybody can read a help file. Compare this to taking an airplane. Most people cannot even estimate the mechanical reliability of an airplane, and the skills of its pilots. But old coffee stains on the seats and overdue paint jobs, while they have no effect on the airworthiness of the plane, are easy to spot and will determine what people think about the plane and the airline.</FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT SIZE="2" FACE="Arial"> </FONT></P>
<P STYLE="margin-top:0;margin-bottom:0;"><FONT FACE="Arial" SIZE="2">So be sure to write a great help file. HelpScribble takes care of all the technical details so you can focus on providing solid content.
Code: Select all
Let>CHM_FONT=Segoe UI
Let>CHM_BASE_COLOR=#BFBC00
Let>REGEX_PATTERN=<FONT[^>]*?SIZE="(5|6)[^>]*?>(.*?/P>)
Let>REGEX_REPLACE_PATTERN=<FONT FACE="%CHM_FONT%" COLOR="%CHM_BASE_COLOR%" SIZE="$1">$2%CRLF%<P><HR></P>
RegEx>REGEX_PATTERN,HTML_CODE,0,,,1,REGEX_REPLACE_PATTERN,HTML_CODE
//this <FONT FACE="Arial" COLOR="#0000FF" SIZE="5"><B>How to Write a Great Help File</B></FONT></P> becomes:
//this <FONT FACE="Segoe UI" COLOR="#BFBC00" SIZE="5"><B>How to Write a Great Help File</B></FONT></P>
// <P><HR></P>
Let>REGEX_PATTERN=<FONT[^>]*?SIZE="(1|2|3|4)".*?>
Let>REGEX_REPLACE_PATTERN=<FONT FACE="%CHM_FONT%"SIZE="$1">
RegEx>REGEX_PATTERN,HTML_CODE,0,,,1,REGEX_REPLACE_PATTERN,HTML_CODE
//this <FONT FACE="Arial" COLOR="#008000" SIZE="2"> becomes:
//this <FONT FACE="Segoe UI" SIZE="2">
//and
//this <FONT FACE="Arial" SIZE="1"> becomes:
//this <FONT FACE="Segoe UI" SIZE="1">
Code: Select all
RegEx>REGEX_PATTERN,TEXT_TO_PARSE,0,MATCHES,,0,,
//MATCHES_1="full match like today"
//MATCHES_1_1="contents of capturing group 1 ($1)"
//MATCHES_1_2="contents of capturing group 2 ($2)"
//...
//MATCHES_1_N="contents of capturing group N ($N)"
Code: Select all
Let>STRING_raw=12345678abcd1234abcd12345678
Let>REGEX_PATTERN=(.{8})(.{4})(.{4})(.{4})(.*)
RegEx>REGEX_PATTERN,STRING_raw,0,,,1,$1-$2-$3-$4-$5,STRING_fixed
MDL>STRING_fixed
If this could squeeze into the next (v16?) release it would be a great addition.Grovkillen wrote: ↑Mon May 15, 2023 3:32 pmWould be great if we could get the capturing groups back just like the "global match". I.e.
Code: Select all
RegEx>REGEX_PATTERN,TEXT_TO_PARSE,0,MATCHES,,0,, //MATCHES_1="full match like today" //MATCHES_1_1="contents of capturing group 1 ($1)" //MATCHES_1_2="contents of capturing group 2 ($2)" //... //MATCHES_1_N="contents of capturing group N ($N)"
