1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

Help nit

Discussion in 'Support' started by Peter Bratton, May 26, 2012.

  1. Peter Bratton

    Joined:
    Jul 1, 2008
    Messages:
    81
    Likes Received:
    0
    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]
     
  2. rconn

    rconn Administrator
    Staff Member

    Joined:
    May 14, 2008
    Messages:
    9,726
    Likes Received:
    80
    It wouldn't be much use for people with 25-line windows if the quick help scrolled the command line out of sight.

    Which is one reason I've said the quick help for TPIPE would be pointless anyway.
     
  3. Peter Bratton

    Joined:
    Jul 1, 2008
    Messages:
    81
    Likes Received:
    0
    It's the same for HELP TPIPE as it is for TPIPE /?
     
  4. rconn

    rconn Administrator
    Staff Member

    Joined:
    May 14, 2008
    Messages:
    9,726
    Likes Received:
    80
    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. Steve Fabian

    Joined:
    May 20, 2008
    Messages:
    3,523
    Likes Received:
    4
    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
     
  6. Steve Fabian

    Joined:
    May 20, 2008
    Messages:
    3,523
    Likes Received:
    4
    [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.
     
  7. rconn

    rconn Administrator
    Staff Member

    Joined:
    May 14, 2008
    Messages:
    9,726
    Likes Received:
    80
    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.
     
  8. Steve Fabian

    Joined:
    May 20, 2008
    Messages:
    3,523
    Likes Received:
    4
    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.
     
  9. rconn

    rconn Administrator
    Staff Member

    Joined:
    May 14, 2008
    Messages:
    9,726
    Likes Received:
    80
    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. Steve Fabian

    Joined:
    May 20, 2008
    Messages:
    3,523
    Likes Received:
    4
    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.
     
  11. rconn

    rconn Administrator
    Staff Member

    Joined:
    May 14, 2008
    Messages:
    9,726
    Likes Received:
    80
    You've invented an imaginary distinction. To the parser (and the TPIPE command), they're simply arguments; there is no concept of an "option" versus a "parameter".
     
  12. Steve Fabian

    Joined:
    May 20, 2008
    Messages:
    3,523
    Likes Received:
    4
    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)
     

Share This Page