FreeCOM - Source - docs - html - commands - appendix.html
Closed this issue · 5 comments
fritzmueller commented
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.
andrewbird commented
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
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
Hope you can follow me. Thx for reading.
PerditionC commented
I believe in this context PR means pull request. I will have a look at this report this weekend. Thanks.
fritzmueller commented
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 <CMD> by <B> and </CMD> bei </B>
same with <OPT> and </OPT>
same with <ARG> and </ARG> ---> I have no idea why they are inside.
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 <BR> for line breaks
added a lot of <p> 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\TEXT
The 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 exists
EXAMPLES:
EXAMPLE: 1
CMD: cmd <in1 <in2
Input stream is redirected to file IN2, because it is the rightmost
one.
EXAMPLE: 2
CMD: cmd <in >out
Input stream is redirected to file IN, the output streams is
redirected into file OUT.
If the file OUT already exists, the old contents is discarded and
replaced by the new one; otherwise, the OUT is created anew.
EXAMPLE: 3
CMD: cmd <in >>out
As example 2, but instead of replacing the contents of OUT, if the
file already exists, the new information is appended to the end of the file.
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 <in >out
Which is similiar to this sequence:
CMD: cmd1 >%TEMP%\t1 <in
CMD: cmd2 <%TEMP%\t1 >%TEMP%\t2
CMD: DEL %TEMP%\t1
CMD: cmd3 <%TEMP%\t2 >out
CMD: DEL %TEMP%\t2
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
* Any remaining body, except a dot (.)
? Any character, except the dos (.);
acts as *, if the last character
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:
* Any file without an extension.
Some commands, such as DIR, interprete a single *
as *.*
a*.* Any file, which first character is
an A, neither the remainder of the filename nor
the extension of the file matters
a?.* same as above
a???.* same as above
a*b.* same as above
a?b.* Any file, which first character is
an A and the third one is a B; the remaining
characters nor the extension matter
file?.txt All files, which first four characters
are FILE and which extension is equal to TXT
\scripts\*.pl Any perl file in the directory \SCRIPTS located in the root directory of the currently selected drive
Warning: There are common mistakes about wildcards,
as DOS has less functional wildcards than other systems, in particular:
a*bc.*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