Help nit

Jul 1, 2008
81
0
74
Montreal
How about formatting the TPIPE help to display one option per line to make it less daunting? Like so:
TPIPE [/input=filename]
[/output=filename]
[/filter=filename]
[/save=filename]
[/unicode=input,output]
[/simple=n]
[/eol=input,output,length]
[/line=start,increment,skipblank,dontnumberblank,format]
[/insert=position,type,string]
[/head=Exclude,LinesOrBytes,Count]
[/tail=Exclude,LinesOrBytes,Count]
[/number=type,value]
[/string=type,string]
[/file=type,filename]
[/dup=RemoveDuplicateLines,IgnoreCase,StartColumn,Length,IncludeOne]
[/comment=text]
[/log=LogFileName]
[/run=InputFileName,OutputFileName,"CommandLine"]
[/merge=type,filename]
[/split=type,SplitSize,SplitChar,SplitCharPos,SplitCharCount,SplitLines,SplitFilename ]
[/grep=Type,IncludeLineNumbers,IncludeFilename,IgnoreCase,CountMatches,PatternType,UTF8,PatternType,Pattern]
[/replace=Type,MatchCase,WholeWord,CaseReplace,PromptOnReplace,Extract,FirstOnly,SkipPromptIdentical,Action,SearchStr,ReplaceStr]
[/xml=Type,IncludeText,IncludeQuotes,MatchCase,BufferSize,Tag,Attribute,EndTag]
 

rconn

Administrator
Staff member
May 14, 2008
12,344
149
The online help has everything listed individually in the "Options" section. I don't know that it's particularly valuable to double the amount of space taken in order to list the options individually in two places on the page. (Particularly since you're not going to be able to understand any of the options without referring to the full text in the Options section anyway!)
 
May 20, 2008
3,515
4
Elkridge, MD, USA
The online help has everything listed individually in the "Options" section. I don't know that it's particularly valuable to double the amount of space taken in order to list the options individually in two places on the page. (Particularly since you're not going to be able to understand any of the options without referring to the full text in the Options section anyway!)

Since each of the individual options has its own unique syntax, which cannot be easily understood from the top-level summary, I suggest not to list them at all - just display

Format: TPIPE option
 
May 20, 2008
3,515
4
Elkridge, MD, USA
[continuing previous post - I could not move cursor past the last line pasted] and possibly add a statement that at least one option must be entered else the command will do nothing.
 
May 20, 2008
3,515
4
Elkridge, MD, USA
Since that's true of just about every command (except for REM, which always does nothing) I don't know that it adds anything useful.
Sorry, I must contradict you. While many commands do require at least one PARAMETER to do anything useful, only TPIPE requires specifying at least one OPTION to be useful. I like to keep my terminology as precise and consistent (and standards conforming) as my code... and my code fails that test more often than my documentation.
 

rconn

Administrator
Staff member
May 14, 2008
12,344
149
Sorry, I must contradict you. While many commands do require at least one PARAMETER to do anything useful, only TPIPE requires specifying at least one OPTION to be useful. I like to keep my terminology as precise and consistent (and standards conforming) as my code... and my code fails that test more often than my documentation.

Sorry, I must contradict your contradiction. In the case of TPIPE, there is no distinction -- every option IS a parameter, and there are no parameters that are not options.
 
May 20, 2008
3,515
4
Elkridge, MD, USA
In the parser, are they processed as parameters or as options?

Regardless, HELP topic TPIPE lists only options, but no parameters. While some of them are more analogous to TCC command parameters then to command options, in the TCC syntax they are all options, not parameters.
 
May 20, 2008
3,515
4
Elkridge, MD, USA
OK, for the parser they are arguments, but in all command descriptions options are listed separately from parameters, with hyperlinks from the short summary to the detailed explanation. Cf. command parameters, which are usually described in the command description. IIRC the parameter vs. option dichotomy goes back to very early versions of PC-DOS, and often options are referred to as switches, separated from the command name and command parameters by the SwitchChar (a valid directive for TCC internal features even in V14 - but does it work for TPIPE?).

Nevertheless, going back to my first two posts in this thread (they were supposed to have been a single submission), I suggested that the long and hard to read list of options for TPIPE should not be included at the top of TPIPE topic in HELP, instead just a single line in the format below (slightly modified from above):
"Format: TPIPE option [option ...]

See list of options below. At least one must be included."

IMHO - matching that of the OP - the compact list just wastes screen space - it is too hard to interpret.

Additional suggestions for this HELP page:

- ANSI is a registered trademark, should not be used for both a character code set NOT conforming to any ANSI standard (e.g., /simple=3) AND for the X3.64 codes (e.g. /simple=14)
- for option field values use this style:
type:
0 - Insert column
1 - Insert bytes
and do not use this style:
Exclude - if 0, include the text; if 1, exclude it
LinesOrBytes - if 0, measure in lines; if 1, measure in bytes
- fewer blank lines (too much scrolling, less overview of each option)
 
Similar threads
Thread starter Title Forum Replies Date
C Documentation Help Nit. REN / RENAME Support 0
R Documentation Help Nit with SETP Support 0
R Documentation Help Nit > bdebugger View Menu Support 0
vefatica Help nit Support 0
C Help Nit Support 0
vefatica Help nit (FFIND and DIR with /S) Support 0
vefatica Help nit Support 0
C Help 'nit Support 0
vefatica v20 help nit Support 12
vefatica Quick help nit Support 0
S Documentation HELP nit: @LINES Support 5
S Documentation HELP Nit - Index - Desktop command Support 0
vefatica IF PLUGIN (help nit?) Support 2
Charles Dye Documentation Another help nit Support 3
S Documentation HELP nit Support 0
S HELP nit: TOC error Support 0
vefatica Help nit Support 2
JohnQSmith Help nit Support 2
vefatica Help nit Support 1
S Help nit Support 0
S Help topic "f_wininfo.htm" - a nit Support 3
S HELP nit Support 0
S HELP nit Support 3
S HELP nit Support 0
S HELP nit Support 0
S HELP nit Support 1
S HELP nit and suggestion Support 2
vefatica Another help nit Support 12
J Help nit Support 2
C Add link to ewriter help to program group... Support 3
samintz How to? Search for %(command) in Help? Support 1
Joe Caverly Favorites in eWriter Help Support 6
Joe Caverly Quick Search in eWriter Help Support 1
vefatica Online help? Support 2
fishman@panix.com HELP!! I just updated to Version 28 and as usual I cannot make extended directory search work. Support 2
JohnQSmith New online help file wrong logo Support 7
Jay Sage Documentation Function @DRIVE Missing in Help Lists Support 0
Charles Dye More help nits Support 0
D Documentation Typo in COPY help Support 0
FreezerBurnt Help making a CMD and TCC compatible batch file Support 7
Joe Caverly Documentation COMMANDS in Version 27 help Support 8
K_Meinhard How to? Help window position Support 7
U Command help on file names Support 5
D Documentation Help "Startup" page does not describe global lists Support 0
vefatica Help disappears? Support 6
rchapmanitt Help Purchasing Support 2
Charles Dye Documentation Help nits: @ZIPFILECRC Support 0
C version help Support 3
Dmitry L. Kobyakov Documentation Error in the Help: the WINDOW command Support 0
vefatica Help for @PID Support 2

Similar threads