Closed fritzmueller closed 1 year ago
andrewbird
commented
1 year ago Hello @fritzmueller, thanks for the report. The best way to get it to read how you would like is to submit a PR, then there's no guessing as to exactly what the correct wording should be.
fritzmueller
commented
1 year ago Hi Andrew,
I assume PR should mean Private Response, all other translations by Google seem to be nonsense. And I found no way to send you a private response. Have a look at the screenshots and you will see that the browser handles most of the text in one line. If this should be correct, I big your pardon.
The example in section batch exits abrupt, see appendix 02 and 02b.
fritzmueller
commented
1 year ago Hope you can follow me. Thx for reading.
PerditionC
commented
1 year ago I believe in this context PR means pull request. I will have a look at this report this weekend. Thanks.
fritzmueller
commented
1 year ago Hi,
referring to appendix.html:
the last batch file was okay. My mistake. So please forget this report.
I tried to update appendix.html to a version that works in Firefox etc.
Main changes:
replaced
replaced < << by < replaced > >> by > replaced & by & replaced % by % corrected redireced to redirected
all this should even work with the latest version of htmlhelp (the one that is not yet published).
I have no idea why the original uses CMD, OPT and ARG.
Most changes by me were at I/O redirection, Pipes, Batch Scripts,
added a lot of
for line breaks
added a lot of
for an empty line to make the text visible.
Please check if "CMD:" is really necessary at the batch examples (I think no, but I left them as they were).
Maybe some other minor changes that I have forgotten.
I beg your pardon, but I am not yet trained in pull requests etc, so I send it directly.
Fritz / Wilhelm Spiegl
Sent: Friday, December 09, 2022 at 1:46 PM From: "Kenneth J Davis" @.> To: "FDOS/freecom" @.> Cc: "fritzmueller" @.>, "State change" @.> Subject: Re: [FDOS/freecom] FreeCOM - Source - docs - html - commands - appendix.html (Issue #87)
I believe in this context PR means pull request. I will have a look at this report this weekend. Thanks.
— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you modified the open/close state.Message ID: @.***>
Appendix to the Description of Features and Implementation Status of FreeCOM
Appendix to the Description of Features and Implementation Status of FreeCOM
Current Directory
The current directory is the default directory of a drive.
DOS stores a default directory for each drive. When a path is specified with a drive specification only, such as D:, it is completed with this default directory of that drive to construct the absolute path to be used.
Current Working Direcory
In opposite to the current directory the current working directory is the absolute path constructed out of the currently selected drive and current directory of that drive.
Path Specification
In DOS an absolute path is constructed out of several components:
drive, directory, filename, and file extension.
like this: D:\DIR1\DIR2\FILENAME.EXT.
The drive is a single letter from A through Z followed by a colon :.
The remaining part of a path consists of similiar components delimited by a single backslash . The last component is also called filename. Each of these components may be formed of a name, up to eight characters long, and an extension, up to three characters long. Both parts are delimited by a single dot .. Although the extension may be absent, the filename must have at least one character. Note: The term filename is not limited to files in the usual sense, but may apply to any name visible in a directory, such as subdirectories and volume labels, as well.
To ease the way to enter a path the user may specify a relative path, rather than an absolute one. In such path one or more components may be missing:
If no drive is specified, what means that no colon is specified, the path is prefixed by the currently selected drive.
If the directory is not prefixed by the backslash or no directory is specified at all, the current directory of the drive is inserted right behind the colon.
Some programs may append an absent extension to the very last filename component.
Examples, assume the current directories of
Drive
Current Directory
C:
\FREEDOS\HELP
D:
\TEMP\TEXTThe currently selected drive is C:.
C:\ The root directory of drive C:.
. The current working directory, ergo: C:\FREEDOS\HELP.
.. The parent directory, ergo: C:\FREEDOS.
D: The current directory of drive D:, ergo: D:\TEMP.
D:. The current directory of drive D:, ergo: D:\TEMP.
D:.. The parent directory of drive D:, ergo: D:.
..\BIN Because there is neither a drive nor a leading backslash, both the currently selected drive and the current directory of that drive is inserted before the given path, ergo: C:\FREEDOS\HELP..\BIN. The embedded component .. has the same meaning as when specified alone: parent directory, though, here in the context of the directory C:\FREEDOS\HELP. That means that the final absolute path is: C:\FREEDOS\BIN.
Path specifications that do not conform to above mentioned format lead to various different behaviour of the various programs, because there is no standard to scan, parse and interprete such patterns. Problems include:
multiple backslashes, multiple dots, multiple colons, or a colon at a position unequal to two, The current directory . or parent directory .. special directories in the context of a root directory, such as C:., C:.., or C:\TEMP.....
Note: The special directories . and .. are no phantom directories or virtual entries, but standard entries of every directory except the root directories. These entries help crash recovery tools, such as CHKDSK or SCANDISK, to find errors within the directory structure and restore it to a valid file tree. Therefore a common assumption that a tripple dot ... directory means parent-of-parent is incorrect, though, might be supported by certain programs.
Standard Rules for Options
Options are prefixed by one forward slash "/", the following character identifies the option and is called option character, for instance: /A
Some commands do accept long option names, where a complete word identifies the option rather than a single character, e.g. /MSG.
Some option may be used in conjunction with an argument. The argument is appended to the option with one colon ":" or one equal sign "=", for instance: /A:hr or /P=fdexec.bat.
Multiple options without argument maybe merged together as a single option with embedded slashes, e.g. /W/S, instead of /W /S. An option with argument may be the last one of such merged options.
Options without arguments enable or disable certain features. Therefore, those options are sometimes called boolean options or flags. Boolean options may be prefixed by a minus "-" sign, in order to disable or turn off the option; otherwise, the option is enabled. Without user invention a boolean option is disabled by default. However, some commands allow the user to change the default settings of certain options, e.g. COPY and DIR.
I/O Redirection
In DOS the standard input and output can be redirected to a file or another device; however, although it is common to use these I/O streams today, some programmers cowardly ignore them for reasons of speed or program size.
If the input stream is redirected to a file or device, instead of polling the keyboard and request the user to interactively enter characters via the keyboard, those characters are read from the file or device. Usually these programs terminate when the file has been read wholely.
If the output stream is redirected to a file or device, instead of issuing the information onto screen, it is dumped into the file or device. Per convention each program has two output streams: one (called standard output) to issue normal information and one (called standard error output) for error messages the user should not miss.
Redirections are specified on command line and effect exactly that command invoked herein, regardless if the command is an external or internal one, an alias or batch script. The utter exception is the FOR command, which requires that the redirection is to apply to the command specified behind the DO keyword rather than FOR itself. If more than one redirection is specified on the command line and they effect the same stream (input, output, or error), the rightmost one superceed any previous one.
Redirections are syntactically specified like this:
EBNF: operator target
EBNF: operator ::= '<' | '>' [ '>' ] EBNF: target ::= file | device
Although it is not relevant where the redirections are placed on the command line, it is common praxis to place them at the end of it. The operators have the following meaning:
Operator
Redirection
<
Input stream
>
Output stream; target file is overwritten
>>
Output stream; output is appended to target, if it already existsEXAMPLES:
EXAMPLE: 1
CMD: cmd <in1 <in2 Input stream is redirected to file IN2, because it is the rightmost one.
EXAMPLE: 2
CMD: cmd
EXAMPLE: 3
CMD: cmd
EXAMPLE: 4
CMD: FOR %a IN (.) DO ECHO %a >out As mentioned earlier, FOR is an exception and passes forth the redirections to each invocation of the command specified right of the DO keyword. So this examples overwrites the output file each time the ECHO command is performed, thus, instead of creating a file list, only the last found file is recorded into OUT.
EXAMPLE: 5
CMD: IF EXIST out DEL out CMD: FOR %a IN (.) DO ECHO %a >>out This sequence eliminate the problem, the IF command is required to actually replace the file rather than appending the file list to the probably existent file.
Pipes
Another form of redirection is piping. Hereby, the output stream of one command is connected to the input stream of another command. Pipes can combine any number of commands this way. Because DOS is no multitasking system, pipes are simulated by spawning the first command with an output redirection capturing the issued information into a temporary file and then the second command with an input redirection from that very same temporary file, on completation of the second command the temporary file is deleted.
EXAMPLES:
EXAMPLE: 1 CMD: cmd1 | cmd2 | cmd3 Which is similiar to this sequence: CMD: cmd1 >%TEMP%\t1 CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 CMD: DEL %TEMP%\t2
EXAMPLE: 2
The first and last command can have an input or output redirection
respectively, like so:
CMD: cmd1 | cmd2 | cmd3
EXAMPLE: 3 The error stream can be piped as well: CMD: cmd1 |& cmd2 | cmd3 Which is similiar to this sequence: CMD: cmd1 >&%TEMP%\t1 CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 CMD: DEL %TEMP%\t2 Here only the error messages of cmd1 are passed into cmd2; the error messages of both cmd2 and cmd3 are issued to the screen.
Nested redirections
Batch scripts or when external programs invoke other programs or another shell, redirections may be nested, e.g.:
Consider the batch file BATCH.BAT:
@ECHO OFF ECHO 1 ECHO 2 >out_2 ECHO 3
which is invoked via:
CMD: BATCH >out_1
When the script BATCH gets executed, the actual output stream is redirected to the file OUT_1. Therefore the output of the first ECHO command is redirected into this file. Because the second ECHO command has its own output redirection, its output is redirected into the file OUT_2. On completion of ECHO the redirection is closed and the former one is restored. What causes that the output of the third ECHO command is redirected into OUT_1 again.
Wildcards
DOS accepts certain placeholders instead of files, so you can specify one or more files with the same wildcard pattern. In opposite to other systems each program expands wildcards individually instead of let the shell do this; however, the shell must epxand wildcards for its internal commands.
FreeCOM supports the standard DOS wildcards as supported by the DOS kernel itself:
Wildcard Meaning
Wildcards are allowed in the last portion of a qualified path, that means behind the last backslash () or colon (:). Wildcards match either before or behind the dot delimiting the filename and its extension. Whether or not directories or volume lables or hidden and system files do match a pattern depends on the command expanding it. Letters match case-insensitively.
Examples:
Pattern Meaning
. Any file in the current directory c:. Any file in the current working directory of drive C:
Warning: There are common mistakes about wildcards, as DOS has less functional wildcards than other systems, in particular:
abc.txt: Any character right of an asterisk up to the dot . or the end of the filename is ignored; this pattern is equal to: a.. a?.?: A question mark ? as the last character of either the filename or file extension has the same effect as an asterisk and does not mean exactly one any character, in particular no character must be present; this pattern is equal to a..
Batch Scripts
The shell lets to automate simple tasks by writing batch scripts. These are plain text files with one command is written at one line. Any command, both internal and external ones, can be used in batch scripts, along with redirections, pipes, environment variable substitions a.s.o. The script is performed line-by-line.
By default, before executing a line, it is displayed onto the screen, in order to prevent this, one can turn off this feature with the ECHO command or prefix each line with the Ad sign (@), e.g.:
CMD: ECHO This line is displayed CMD: @ECHO This line is NOT displayed Commonly batch scripts start with the line: CMD: @ECHO OFF in order to turn off to echo each line furtherly in the script processing and to suppress to echo the line itself, too.
Lines starting with a colon (:) label this particular script line, in order to be jumped to with the GOTO command, e.g.:
CMD: @ECHO OFF CMD: IF "%1"=="" GOTO useage CMD: ECHO argument1=%1 CMD: ECHO argument2=%2 CMD: ECHO argument3=%3 CMD: GOTO ende CMD: :useage CMD: ECHO Useage: %0 {arguments}... CMD: :ende If the script is invoked with no argument, line 2 performs the GOTO command and, thus, skips the lines 3 through 7 and proceeds with line 8. Otherwise the three ECHO commands are invoked and the GOTO command of line 6 skips the ECHO'ing of the error message in line 8 and proceeds in line 9.
If the shell hits a line starting with a colon, it is silently skipped; not even redirections are evaluated in opposite to the REM command.
When the shell reaches the end of the file, the batch processing terminates. The errorlevel of the last spawned external command remains unchanged. Because the shell closes the batch script and re-opens it each time a command, for both internal and external ones, is invoked, one can savely replace floppy disks during a batch processing, e.g.:
CMD: @ECHO OFF CMD: ECHO Copying disk1 CMD: COPY files*. C:%1 CMD: :disk2 CMD: PAUSE Insert disk #2, then hit ENTER CMD: IF NOT EXIST disk2 GOTO disk2 CMD: ECHO Copying disk2 CMD: COPY files*. C:%1 CMD: :disk3 CMD: PAUSE Insert disk #3, then hit ENTER CMD: IF NOT EXIST disk2 GOTO disk3 CMD: ECHO Copying disk3 CMD: COPY files*.* C:%1 CMD: ECHO Copying done. When a batch file is invoked within another batch file, the previous ones does not proceed once the called one terminates, regardless of the nesting level; this is called chaining, one chains to another program and does not intend to come back. To have a batch script behave like an external program in this regard, it must be invoke via the CALL command, e.g.:
CMD: @ECHO OFF CMD: ECHO %0 - line 2 CMD: CALL batch2 CMD: ECHO %0 - line 4 and BATCH2.BAT: CMD: ECHO %0 - line 1
There seems to be bad readable html code in appendix.html in the following sections:
a) batch scripts, section: ....When a batch file is invoked within another batch file, the previous ones does not proceed once the called one terminates, regardless of the nesting level; this is called chaining, one chains to another program and does not intend to come back. To have a batch script behave like an external program in this regard, it must be invoke via the CALL command, e.g.: .....
The following example is not complete in my eyes. And it is almost not readable with an actual Browser.
b) same with section Pipes - examples. .... EXAMPLES: EXAMPLE: 1 CMD: cmd1 | cmd2 | cmd3 Which is similiar to this sequence: CMD: cmd1 >%TEMP%\t1 CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2 CMD: DEL %TEMP%\t1 CMD: cmd3 <%TEMP%\t2 CMD: DEL %TEMP%\t2 EXAMPLE: 2 The first and last command can have an input or output redirection respectively, like so: ......
Not very important, but I wanted to send you a short hint.