simmy@ocean.ocean.fsu.edu (Simmule Turner) (08/28/89)
Several people have expressed interest in doing some documentation, for programs. I normally use MROFF, by Carl Kreider. It is available on listserv@pucc.BITNET. What follows are the tools I use to create man pages (whenever I do them). I prefer distributing the unformatted docs myself. simmy #! /bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #! /bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create the files: # anos9.macros # man.template # popen.3 # popen.fmt # This archive created: Sun Aug 27 13:41:58 1989 export PATH; PATH=/bin:$PATH if test -f 'anos9.macros' then echo shar: will not over-write existing file "'anos9.macros'" else cat << \SHAR_EOF > 'anos9.macros' .* $Header: mroff.man,v 1.0 7/20/88 SrT $ .* .* Simmule Turner simmy@ocean.ocean.fsu.edu 70651,67 .* .* Unix-like man macros. .* .* To print under unix cut at the cut line. .dm TP .in +10 .ti -5 .fi .* User should make all arguments the same length .* by adding unpaddable spaces. "-x\ \ " \\$0 .. .dm TH .he '\\$0(\\$1)'OS-9/6809'\\$0(\\$1)' .. .dm SH .sp 1 .in \\$0 .in +5 .. .fo 'Page %''(printed \nM/\nD/\nY)' .po 5 .fi .nj .rm 72 .* .* -------Remove up to here to print under Unix------- SHAR_EOF fi # end of overwriting check if test -f 'man.template' then echo shar: will not over-write existing file "'man.template'" else cat << \SHAR_EOF > 'man.template' .so ../an.macros .TH ALARM 2 .SH NAME alarm\ -\ set a process alarm clock .SH SYNOPSIS .SH DESCRIPTION .SH EXAMPLES .SH "SEE ALSO" .SH DIAGNOSTICS .SH BUGS .SH AUTHOR .nf Simmule R Turner 2008 Gardenbrook Lane Tallahassee, Fl 32301 .sp CIS: 70651,67 DELPHI: simmy GENIE: simmy PLINK: OKS619 Internet: simmy@ocean.ocean.fsu.edu UUCP: ..!uunet!ocean.ocean.fsu.edu!simmy SHAR_EOF fi # end of overwriting check if test -f 'popen.3' then echo shar: will not over-write existing file "'popen.3'" else cat << \SHAR_EOF > 'popen.3' .so ../an.macros .TH POPEN 3 .SH NAME popen, pclose - initiate pipe to/from a process .SH SYNOPSIS .sp 1 .nf #include <stdio.h> FILE *popen (command, type) char *command, *type; int pclose(stream) FILE *stream; .fi .SH DESCRIPTION Popen creates a pipe between the calling program and the command to be executed. Unlike the unix popen, this version does not use the shell (no i/o redirection, wildcards, etc). Arguments to popen are pointers to null-terminated strings. Command consists of any legal OS-9 command, with or without arguments. Type is an I/O mode, either "r" for reading or "w" for writing. The returned stream pointer is one that can be written to, if the I/O mode is "w", or read from if the mode is "r". .sp 1 A stream opened by popen should be closed by pclose. Pclose waits for the process created by popen to die and returns the exit status of the command. .SH EXAMPLES The following are typical calls: .in +5 .nf .sp 1 /* Print current data directory */ #define MAXLEN 128 char buffer[MAXLEN], *command = "pwd"; FILE *fp, *popen(); if ((fp = popen(command,"r")) != (FILE *)NULL) { if (fgets(buffer,MAXLEN,fp) != (FILE *)NULL) printf("Current directory is %s\\n",buffer); pclose(fp); } .sp 2 /* Send a mail message to Joe Blow */ char buffer[] ="Go home you jerk\\n", *command = "mail joe"; FILE *fp, *popen(); if ((fp = popen(command,"w")) != (FILE *)NULL) { fputs(buffer,fp); fputs(".\\n",fp) pclose(fp); } .in .fi .SH "SEE ALSO" fclose, fopen, stdio, wait .SH DIAGNOSTICS popen returns a null pointer if process cannot be created. .sp 1 pclose returns -1 if stream is not associated with a "popened" command. .SH BUGS Be careful of writing to processes whose output comes to stdout, the screen display may become garbled. .SH AUTHOR .nf Simmule R Turner 2008 Gardenbrook Lane Tallahassee, Fl 32301 .sp CIS: 70651,67 DELPHI: simmy GENIE: simmy PLINK: OKS619 Internet: simmy@ocean.ocean.fsu.edu UUCP: ..!uunet!ocean.ocean.fsu.edu!simmy SHAR_EOF fi # end of overwriting check if test -f 'popen.fmt' then echo shar: will not over-write existing file "'popen.fmt'" else cat << \SHAR_EOF > 'popen.fmt' POPEN(3) OS-9/6809 POPEN(3) NAME popen, pclose - initiate pipe to/from a process SYNOPSIS #include <stdio.h> FILE *popen (command, type) char *command, *type; int pclose(stream) FILE *stream; DESCRIPTION Popen creates a pipe between the calling program and the command to be executed. Unlike the unix popen, this version does not use the shell (no i/o redirection, wildcards, etc). Arguments to popen are pointers to null-terminated strings. Command consists of any legal OS-9 command, with or without arguments. Type is an I/O mode, either "r" for reading or "w" for writing. The returned stream pointer is one that can be written to, if the I/O mode is "w", or read from if the mode is "r". A stream opened by popen should be closed by pclose. Pclose waits for the process created by popen to die and returns the exit status of the command. EXAMPLES The following are typical calls: /* Print current data directory */ #define MAXLEN 128 char buffer[MAXLEN], *command = "pwd"; FILE *fp, *popen(); if ((fp = popen(command,"r")) != (FILE *)NULL) { if (fgets(buffer,MAXLEN,fp) != (FILE *)NULL) printf("Current directory is %s\n",buffer); pclose(fp); } /* Send a mail message to Joe Blow */ char buffer[] ="Go home you jerk\n", *command = "mail joe"; FILE *fp, *popen(); Page 1 (printed 1/31/89) POPEN(3) OS-9/6809 POPEN(3) if ((fp = popen(command,"w")) != (FILE *)NULL) { fputs(buffer,fp); fputs(".\n",fp) pclose(fp); } SEE ALSO fclose, fopen, stdio, wait DIAGNOSTICS popen returns a null pointer if process cannot be created. pclose returns -1 if stream is not associated with a "popened" command. BUGS Be careful of writing to processes whose output comes to stdout, the screen display may become garbled. AUTHOR Simmule R Turner 2008 Gardenbrook Lane Tallahassee, Fl 32301 CIS: 70651,67 DELPHI: simmy GENIE: simmy PLINK: OKS619 Internet: simmy@ocean.ocean.fsu.edu UUCP: ..!uunet!ocean.ocean.fsu.edu!simmy Page 2 (printed 1/31/89) SHAR_EOF fi # end of overwriting check # End of shell archive exit 0 -- Simmule Turner |Arpa: simmy@nu.cs.fsu.edu | "Wait until it is Florida State Univ |Uucp: gatech!nu.cs.fsu.edu!simmy | finished, it will 444 OSB | Cis: 70651,67 Genie:simmy | be great" Tallahassee, FL 32306 | Tel: +1 904 644 1573 | simmy