$! $!=head1 NAME $! $!B<p4help2perfhlb.com> - convert Perforce help topics to a VMS PERFORCE.HLB $!help library with HLP topics $! $!=head1 SYNOPSIS $! $! @p4help2perfhlb $! $!After that refer to the INSTALLATION instructions below. $! $!=head1 DESCRIPTION $! $!This procedure will create a PERFORCE.HLB help library in $!the default directory. $! $!Since one should not use "p4" as a global symbol on VMS, $!this procedure has provision for replacing the string "p4" $!with a substitute (the default substitute is "perf") throughout $!the resultant documentation. $! $!=head1 ENVIRONMENT $! $!The Perforce symbol and P4* logicals ought to be set up before $!running this procedure. This procedure expects to be able $!to access the perforce help via commands such as: $! $! $ perforce help $! $!that is, with "perforce" as a foreign command for the PERFORCE.EXE $!or P4.EXE client (Contrary to the documentation from Perforce, $!one ought not use "p4" as a global symbol on VMS, oddly the reasons $!are subtle: the p4 parameter in DCL procedures and subroutines is $!typically a local symbol that defaults to "" the empty string value. $!If you want to see why try running the command: $! $! $ p4 info $! $!from the command line (it will work) then run it either as a DCL $!procedure run with @PROC_NAME or via SUBMIT PROC_NAME - and note $!that it will not work in either case. $! $!If you want to see more verbose output, and not delete intermediate $!*.HLP files, then issue: $! $! $ define P4HELP_DEBUG TRUE $! $!prior to executing this procedure. Note that defining that logical $!name will also leave behind all intermediate files. $! $!=head1 INSTALLATION $! $!There are several ways to make use of the converted $!documentation in the generated PERFORCE.HLB file via the $!VMS HELP command. These are outlined below: $! $!=head2 in SYS$HELP:HELPLIB.HLB $! $!If you have the necessary access to do so then you can install $!the PERFORCE topic into the system wide default help library $!by first extracting it from the PERFORCE.HLB and then replacing $!it into the system help library with the commands: $! $! $ library/extract=PERFORCE/output=PERFORCE.HLP PERFORCE.HLB $! $ library/replace/help SYS$HELP:HELPLIB.HLB PERFORCE $! $!After that accessing the help topic is simply a matter of: $! $! $ help perforce $! $!=head2 via HLP$LIBRARY_n logical name $! $!A convenient way to access the PERFORCE.HLB help library through $!VMS HELP is to use the HLP$LIBRARY logical name like so: $! $! $ define HLP$LIBRARY disk:[dir]perforce $! $!After that accessing the help topic requires specifying: $! $! $ help @perforce $! $!Note that if HLP$LIBRARY is already defined then try HLP$LIBRARY_1. $!If HLP$LIBRARY_'i' is already taken then try HLP$LIBRARY_'i+1'. $!You should be able to copy PERFORCE.HLB to any disk or directory on $!your system. Note that "official" system documentation usually $!resides in SYS$HELP:. $! $!=head2 via the /LIBRARY qualifier to HELP $! $!An alternative would be to use the /LIBRARY qualifier with HELP $!like so: $! $! $ help/library=sys$disk:[]perforce $! $!If you copy PERFORCE.HLB to SYS$HELP: then you could use: $! $! $ help/library=perforce $! $!For further information see HELP HELP. $! $!=head1 FILES $! $!It is recommended that you run this procedure in an otherwise empty $!directory (particularly if you have defined the logical name P4HELP_DEBUG). $! $!This procedure creates a file PERFORCE.HLB by default. $! $!The following temporary files are deleted by default upon normal $!execution of this procedure. If that fails for you then perhaps $!you need to adjust your default protection. Use SHOW PROTECTION $!to see your default. Use SET PROTECTION/DEFAULT to adjust. $!If on the other hand you want temporary files to not be deleted $!on execution then issue DEFINE P4HELP_DEBUG "TRUE" before running $!this procedure. $! $!=over 4 $! $!=item * P4HELP2PERFHLP.FDL $! $!=item * P4HELP2PERFHLP.EDT $! $!Is used if the p4subst internal symbol is not an empty DCL string $!(p4subst is "perf" by default). $! $!=item * 'topic'.hlp_2 'topic'.hlp_1 'topic'.hlp $! $!For each "perf help" topic three temporary files may be generated $!including PERFORCE.HLP, COMMANDS.HLP_2, etc. $! $!=back $! $!=head1 DIAGNOSTICS $! $!You might encounter one or more of the following messages: $! $!=over 4 $! $!=item * The "p4subst" symbol is missing or improperly assigned. Edit P4HELP2PERFHLB.COM $! $!Recommend that you take a look for the p4subst string in this $!procedure and modify it to correspond the the command that you $!want to use in place of 'p4' in the documentation. $! $!=item * The "perforce" symbol is missing. $! $!This procedure uses PERFORCE as a foreign symbol to conjure up the VMS $!Perforce client. It needs PERFORCE to be assigned in addition to your $!possible local use of "''P4SUBST'". $! $!=item * The P4PORT logical name is missing. $! $!Use the command: DEFINE/JOB P4PORT "yourserver.yourcompany.com:port". $! $!=item * Perforce connection problems detected. Will not proceed. $! $!This procedure was unable to run the command C<$PERFORCE INFO> $!successfully. You might want to make sure that your P4PORT logical $!name is corrent, and that p4d is running on your server. Run: $!PERFORCE INFO from the command line until something reasonable is $!returned. $! $!=back $! $!=head1 AUTHOR $! $!Peter Prymmer pprymmer@factset.com. $! $!=head1 TRADEMARK $! $!"VMS" is a trademark owned by Hewlett-Packard/Compaq Computer Corporation. $! $!=head1 HISTORY $! $! 5-SEP-2002: started and submitted to //public/peter_prymmer. $! $! $Id: //guest/peter_prymmer/p4help2perfhlb.com#1 $ $! $Change: 2082 $ $! $DateTime: 2002/09/05 12:33:29 $ $! $Revision: #1 $ $! $Author: peter_prymmer $ $! $!=cut $! $ !-------------------------------------------- $ ! Some configuration variables $ !-------------------------------------------- $ ! $ ! The 'p4subst' string is a replacement for "p4" in the help $ ! topics. Use the foreign symbol (abbreviation) appropriate $ ! for your installation. For example, we use the foreign symbol: $ ! $ ! $ perf*orce :== $DKA100:[PERFORCE]PERFORCE.EXE $ ! $ ! Hence, for us it makes sense to use: $ ! $ ! $ p4subst = "perf" $ ! $ ! in this procedure, since the asterisk in the symbol allows us to $ ! unambiguously abbreviate down to "perf". $ ! $ ! Leave uncommented the following if you want a global s/p4 /perf / $ ! substitution to take place (this is the default): $ ! $ p4subst = "perf" $ ! $ ! Uncomment the following if you want no command name $ ! substitution to take place (i.e. 'p4' appears as 'p4' $ ! throughout all the help library): $ ! $! p4subst = "" $ ! $ ! Uncomment the following if you want a global s/p4 /perforce / $ ! substitution to take place: $ ! $! p4subst = "perforce" $ ! $ ! Note below that a symbol "perforce" is used by this procedure. $ ! $ !-------------------------------------------- $ ! $ ! If you would prefer to leave undocumented and/or obsolete features $ ! out of the help library then leave the following uncommentd: $ ! $ want_undoc := false $ ! $ ! If you want the topic that corresponds to "perf help undoc" in $ ! your help library then uncomment the following line: $ ! $! want_undoc := true $ ! $ !-------------------------------------------- $ ! End configuration variables $ ! (there is further room for site specific customization - see below) $ !-------------------------------------------- $ ! $ ! Some commonly needed local symbols $ ! $ echo := write sys$output $ warn := write sys$error $ ! $ ! Rather than using SET SYMBOL or DELETE/SYM/GLOBAL $ ! we guard against meddlesome DCL command verb overrides $ ! with local symbols: $ ! $ copy := copy $ delete := delete $ edit := edit $ ! $ ! Check that the p4subst symbol was properly set up by editing of $ ! this preocedure. $ ! $ if f$type(p4subst) .nes. "STRING" $ then $ warn "The ""p4subst"" symbol is missing or improperly assigned." $ warn "Edit " + f$environment("PROCEDURE") $ exit 44 $ endif $ ! $ ! Check that environment is OK for running the perforce help client. $ ! Recommend that you do not attempt to DEFINE things here. $ ! $ if f$type(perforce) .eqs. "" $ then $ warn "The ""perforce"" symbol is missing." $ exit 44 $ endif $ if f$trnlnm("P4PORT") .eqs. "" $ then $ warn "The P4PORT logical name is missing." $ exit 44 $ endif $ ! $ ! Check that Perforce (client and server) are running $ ! $ define/user_mode SYS$OUTPUT NL: $ perforce info $ if $severity .ne. 1 $ then $ warn "Perforce connection problems detected. Will not proceed." $ exit 44 $ endif $ ! $ ! Typical "perf help" output attributes have an RFM of "STMLF" $ ! Fortunately the LIBRARY/HELP command can handle either "STMLF" or "VFC". $ ! This fdl file will be used by the hlp_header subroutine and deleted later. $ ! $ create p4help2perfhlp.fdl $ deck RECORD FORMAT STREAM_LF $ eod $ ! $hlp_header: subroutine $ ! $ ! p1 file spec (e.g. perforce.hlp) $ ! p2 header level (e.g. "1" as string not integer) $ ! p3 header string (e.g. "PERFORCE") $ ! $ create/fdl=p4help2perfhlp.fdl 'p1' $ open/append HLP_HEAD 'p1' $ write HLP_HEAD "''p2' ''p3'" $ write HLP_HEAD "" $ close HLP_HEAD $ exit $endsubroutine ! hlp_header $ ! $ if p4subst .nes. "" $ then $ open/write command p4help2perfhlp.edt $ ! $ ! Note that the space in the substitution strings means that we $ ! do not replace things like "P4Web", "p4ftp", or "p4d". $ ! $ write command "s/p4 /''p4subst' /w" $ write command "exit" $ close command $ endif $ ! $p4_substitute: subroutine $ ! $ ! p1 input file spec (e.g. perforce.hlp_1) $ ! p2 output file spec (e.g. perforce.hlp_2) $ ! $ if p4subst .nes. "" $ then $ if .not. f$trnlnm("P4HELP_DEBUG") then define/user_mode SYS$OUTPUT NL: $ edit/edt/command=p4help2perfhlp.edt 'p1' /output='p2' $ else $ copy/nolog/noconfirm 'p1' 'p2' $ endif $ exit $endsubroutine ! p4_substitute $ ! $ ! Calling the main "1" topic HELP makes it accessible via "HELP @PERFORCE" $ ! otherwise it would be necessary to use "HELP @PERFORCE PERFORCE" $ ! $ ! call hlp_header "perforce.hlp" "1" "PERFORCE" $ call hlp_header "perforce.hlp" "1" "HELP" $ define/user_mode SYS$OUTPUT perforce.hlp_1 $ perforce help $ call p4_substitute perforce.hlp_1 perforce.hlp_2 $ append perforce.hlp_2 perforce.hlp $ ! $ !-------------------------------------------- $ ! $ ! If you want to add local documentation to the top level $ ! you could do so here. For example: $ ! $ !-------------------------------------------- $ ! $ ! $ open/append P4HLP perforce.hlp $ ! $ write P4HLP " For local documentation see:" $ ! $ write P4HLP " http://www.ourcompany.com/p4_local_guide.html" $ ! $ close P4HLP $ ! $ open/read PERF perforce.hlp_1 $help_loop: $ read/end=eoperf PERF line $ line = f$edit(line,"TRIM,COMPRESS") $ if f$extract(0,8,line) .eqs. "p4 help " $ then $ topic = f$element(2," ", line) $ if topic .nes. "command" $ then $ call hlp_header "''topic'.hlp" "1" 'f$edit(topic,"UPCASE")' $ define/user_mode SYS$OUTPUT 'topic'.hlp_1 $ perforce help 'topic' $ call p4_substitute 'topic'.hlp_1 'topic'.hlp_2 $ append 'topic'.hlp_2 'topic'.hlp $ ! $ !-------------------------------------------- $ ! $ ! If you want to add local ENVIRONMENT documentation to this level $ ! you could do so here. For example: $ ! $ !-------------------------------------------- $ ! $ ! $ if topic .eqs. "environment" $ ! $ then $ ! $ open/append P4HLP 'topic'.hlp $ ! $ write P4HLP " For ourcompany use please define:" $ ! $ write P4HLP " $ define/job P4PORT perforce.ourcompany.com:1666" $ ! $ close P4HLP $ ! $ endif $ ! $ if topic .eqs. "commands" .or. topic .eqs. "simple" $ then $ open/read COMMANDS 'topic'.hlp_1 $command_loop: $ ! Note that there are assumptions about the format of the $ ! "perforce help commands" and "perforce help simple" output $ ! made here. $ read/end=eocommands COMMANDS command_line $ command_line = f$edit(command_line,"TRIM,COMPRESS") $ command = f$element(0," ",command_line) $ if command .nes. "" .and. - ! simple blank line command .nes. "Perforce" .and. - ! From "perforce help commands" command .nes. "Most" ! From "perforce help simple" $ then $ call hlp_header "''command'.hlp" "2" 'f$edit(command,"UPCASE")' $ define/user_mode SYS$OUTPUT 'command'.hlp_1 $ perforce help 'command' $ call p4_substitute 'command'.hlp_1 'command'.hlp_2 $ append 'command'.hlp_2 'command'.hlp $ append 'command'.hlp 'topic'.hlp $ if .not. f$trnlnm("P4HELP_DEBUG") $ then $ delete/nolog/noconfirm 'command'.hlp_2; $ delete/nolog/noconfirm 'command'.hlp_1; $ delete/nolog/noconfirm 'command'.hlp; $ endif $ endif $ goto command_loop $eocommands: $ close COMMANDS $ endif $ append 'topic'.hlp perforce.hlp $ if .not. f$trnlnm("P4HELP_DEBUG") $ then $ delete/nolog/noconfirm 'topic'.hlp_2; $ delete/nolog/noconfirm 'topic'.hlp_1; $ delete/nolog/noconfirm 'topic'.hlp; $ endif $ endif $ endif $ goto help_loop $ ! $eoperf: $ close PERF $ ! $ if want_undoc $ then $ topic = "undoc" $ call hlp_header "''topic'.hlp" "1" 'f$edit(topic,"UPCASE")' $ define/user_mode SYS$OUTPUT 'topic'.hlp_1 $ perforce help 'topic' $ call p4_substitute 'topic'.hlp_1 'topic'.hlp_2 $ append 'topic'.hlp_2 'topic'.hlp $ append 'topic'.hlp perforce.hlp $ if .not. f$trnlnm("P4HELP_DEBUG") $ then $ delete/nolog/noconfirm 'topic'.hlp_2; $ delete/nolog/noconfirm 'topic'.hlp_1; $ delete/nolog/noconfirm 'topic'.hlp; $ endif $ endif $ ! $ library/help/create perforce perforce $ if .not. f$trnlnm("P4HELP_DEBUG") $ then $ delete/nolog/noconfirm perforce.hlp; $ delete/nolog/noconfirm perforce.hlp_1; $ delete/nolog/noconfirm perforce.hlp_2; $ delete/nolog/noconfirm p4help2perfhlp.fdl; $ if p4subst .nes. "" $ then $ delete/nolog/noconfirm p4help2perfhlp.edt; $ endif $ endif $ ! $ exit
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#1 | 2082 | peter_prymmer |
This procedure uses a combination of the Perforce client for VMS, DCL, and EDT to turn "perforce help" topics into a PERFORCE.HLB VMS help library on VMS. It will only run on VMS. The procedure is customizable and it is recommended that you read the extensive documentation in DCL $! comments at the head of the file for further types and PERFORCE.HLB installation tips. |