Help nit

Jul 1, 2008
81
0
71
Montreal
#1
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
10,788
97
#4
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!)
 
#5
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
 
#8
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
10,788
97
#9
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.
 
#10
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.
 
#12
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)