summaryrefslogtreecommitdiff
path: root/web/yacco2/READMEv1.1.w
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/yacco2/READMEv1.1.w
Initial commit
Diffstat (limited to 'web/yacco2/READMEv1.1.w')
-rw-r--r--web/yacco2/READMEv1.1.w449
1 files changed, 449 insertions, 0 deletions
diff --git a/web/yacco2/READMEv1.1.w b/web/yacco2/READMEv1.1.w
new file mode 100644
index 0000000000..5a3691697f
--- /dev/null
+++ b/web/yacco2/READMEv1.1.w
@@ -0,0 +1,449 @@
+@q file: READMEv1.1.w@>
+\input "supp-pdf"
+\input"/usr/local/yacco2/diagrams/o2mac.tex"
+@** Comments on \Yacco2's |READMEv1.1| file --- Date: \today.\fbreak
+\ptindent{Project: \Yacco2 --- Multi-threaded lr(1) Compiler/compiler system}
+\ptindent{Distributed under license: Mozilla Public License, v. 2.0.}
+\ptindent{Distribution Date: \today}
+\ptindent{Distribution version: 1.1}
+\ptindent{Comments: Currently for the Unix flavoured Platforms}
+\ptindent{Author: Dave Bone}
+\ptindent{Support email: cc.yacco2{\char 64}yahoo.ca}
+\ptindent{Contributors list:}
+\INDENT{.75in}{Dave Bone}
+\fbreak
+\fbreak
+The distribution contains the programs: compiler/compiler {\it{\O2}} and its linker {\it{\O2linker}}, along
+with its runtime library {\it{yacco2}}. There are build scripts for platforms: Apple, GNU, Solaris.
+Various documents, grammars, reference manual, quality assurance suites, and generated c++ source code are included.
+These items are elaborated upon further within this document.
+
+@*2 License.\fbreak
+\Yacco2's distributed source code is subject
+to the terms of the Mozilla Public License, v. 2.0.
+If a copy of the MPL was not distributed with this file, you can obtain one at http://mozilla.org/MPL/2.0/.
+\fbreak
+\fbreak
+As best as I could, the ``Literate programming'' w type files
+contain a reference to this license along with their generated documents.
+The c++ source files generated from the w files {\bf {do not and will not have any comments
+referencing this license but are also subject to its terms}}.
+The {\it {ctangle}} program generating the c++ code does not emit programmer c type comments.
+It emits ``\#line'' macro references to the w file and only c comments to its gened document's section number.
+Any discovered license omissions required to be referenced within \Yacco2's Project files
+are still covered by this license and
+will be corrected in future distributions.
+\fbreak
+\fbreak
+@*2 Version |v1.1| --- minor fixes.\fbreak
+\ptindent{\derives{} Regenerating Yacco2 c++ code emitted improper license comments that produced compile errors}
+\ptindent{\derives{} Renamed diagrams+etc folder to diagrams}
+
+
+@*2 README literate programming.\fbreak
+This ``READMEv1.1.w'' file is run thru the {\it cweave}
+ progam to generate a tex file: cweave ``READMEv1.1.w''.
+The {\bf{v1.1}} suffix in its name is the distribution's version.
+Then the program {\it pdftex} is run to create its pdf document: pdftex ``READMEv1.1.tex''.
+Literate programming at the install documentation level that u are now reading.
+@*2 Comments on 1st attempt at ``Open Source''.\fbreak
+Project \Yacco2{} is my first attempt at ``Open Source'' software.
+There are propably faux pas made by my lack of experience but I'm willing to learn from the community.
+My ears, eyes, and grey cells are open to your suggested refinements.
+Harnessed non-determinism thru threading opens up parallel activities. The thought experiment stepping out
+with arbitration deciding multiple outcomes.
+Interesting when a thread becomes a computational universe having time displaying its trails of activities...
+
+
+@*1 Some installation concerns.\fbreak
+Here is a list of questions/answers to help u install and get things going.
+
+@*2 How is \Yacco2 installed?.\fbreak
+Grab a copy of the system and place it on your computer.
+It comes as a zipped file named {\bf{yacco2.zip}}.
+Depending on your run platform, either double click the zipped file
+or run from the command-line-interface using an unzip program like gunzip.
+Once unzipping its contents, the {\bf{yacco2}} folder
+contains subdirectories of text
+files aka grammars and ``literate programs'', the c++ source code,
+binary static libraries of \Yacco2, and the 2 executeable programs
+{\it o2} and {\it o2linker}
+which are the compiler/compiler and its linker.
+
+@*2 Where is \Yacco2 installed?.\fbreak
+The {\bf{yacco2}} folder should be copied to the {\bf{/usr/local/}} folder.\fbreak
+\fbreak
+This distribution contains the executeables and libraries
+{\bf prebuilt for an Apple laptop running Maverick}.
+Other platforms will need to be built using the instructions below.
+This comment also holds for older Apple platforms like the ``Cat'' series.
+
+A ``drag and drop'' attitude it is to installing \Yacco2
+placed in {\bf{/usr/local/}}.
+It is self contained. To thrown it out just drag
+ the ``\Whereyacco2'' folder into the trash bin and delete it
+or use the Unix ``rm'' utility to delete it.
+
+For example if u unzipped \Yacco2 into your desktop folder, then
+the following {\it{Bash}} CLI move command on the Apple platform is:\fbreak
+\ptindent{1) cd \char 126/DeskTop \# example Apple desktop holding yacco2 folder}
+\ptindent{2) mv -f yacco2 /use/local/ \# move the yacco2 folder}
+Substitute your own folder name containing yacco2 for the above ``cd'' command.
+U can also use a ``drag-and-drop'' to do it.
+For the Apple platform, u can unhide the hidden folders shown by ``Finder''
+or use Finder's ``cmd-shift-G'' key combination and type in the
+``/usr/local/'' to see its contents in the Finder's screen.
+Now ``drag-and-drop'' the {\bf{yacco2}} folder into {\bf{/usr/local/}}.
+Other platforms have their version of ``drag-and-drop'' to move \Yacco2.
+
+@*2 What \Cpp{} compiler does it require to compile/install \Yacco2{} system?.\fbreak
+The Apple environment needs Xcode or a development system like GNU.
+For the other platforms, a development system with a \Cpp{} compiler
+and a run time library supporting multi-threading.
+
+This distribution already has the {\it o2} and {\it o2linker} programs installed along
+with the {\it yacco2} library
+for the latest Maverick Apple platform.
+So u can stop the balance of the installation
+for the Apple if u are running Maverick.
+For older Apple Operating systems like the ``Cat'' series, they require u to do some adjustments
+to the Apple scripts below.
+There are {\it bash} comments in these scripts on the variables to set.
+
+
+@*2 How to install \Yacco2.\fbreak
+Once you have placed \Yacco2{} system in {\bf ``/usr/local/''} on either your laptop or server, you will find
+the following Bash scripts
+where each script's suffix name indicates the platform to run the script under.\fbreak
+\ptindent{1) bld\_bash\_APPLE}
+\ptindent{2) bld\_bash\_GNU}
+\ptindent{3) bld\_bash\_SOLARIS}
+You run one of the above scripts with the {\it bash} command-line-interface(CLI).
+Each script is documented with references to other scripts of {\bf makefile\_xxx} where xxx is
+the platform to build
+the subcomponents of \Yacco2. Have a read, they don't bite.
+
+@*3 Possibly out-of-date --- GNU and Solaris scripts.\fbreak
+Possibly points 2 + 3 could be out-of-date as I'm now developing exclusively on the Apple
+MacPro / Xcode environment. These scripts should clue u into what is
+required to get them running on a more up-todate platform.
+Once upon a time they worked but time has changed the Apple script and not them!
+So use the Apple script as a guide to get the other scripts working.
+I'm sure the \Cpp{} compiler and its supporting libraries will be out-of-date.
+
+@*3 Run the installation script.\fbreak
+Here are the bash commands to install the complete system on the Apple MacPro system:\fbreak
+\ptindent{1) cd \Whereyacco2}
+\ptindent{2) . |bld_bash_APPLE|}
+The script has commented out other options that u can use for
+other things like gening the \Cweb{} files
+to building debug executeables. Ditto on the other Operating system scripts.
+\fbreak
+\fbreak
+{\bf Note}:
+\fbreak
+In the ./bin folder, there are the latest executeables for
+the Apple MacPro ``OS X 10.9.2’’/ Xcode 5.1.1: \O2{} and \O2linker
+along with the libraries: {\it yacco2} in ``\Whereyacco2/library/lib/Release'' for u
+to link your own compiler to,
+and {\it o2grammars} in ``\Whereyacco2/compiler/grammars/lib/Release''
+for the \Yacco2{} programs to build against.
+Ready baked for u to try if u are on an Applelite.
+
+
+@*3 Other OPs: GNU, SOLARIS for bld\_bash\_XXX and makefile\_XXX scripts.\fbreak
+To provide consistency, scripts per run platform were written rather than
+depend on a specific development framework like Apple's Xcode.
+If u use a development framework, these scripts will clue u to the ingredients needed to
+map \Yacco2's components to your framework.
+
+You will probably need {\bf to edit} the GNU or Solaris scripts regarding the C++
+libraries versions needed.
+The referenced {\bf makefile\_APPLE} scripts per subfolder
+like {\bf \Whereyacco2/library} in the {\bf bld\_bash\_APPLE} script
+uses the latest 64 bit LLVM compiler toolset under
+Apple's latest operating Maverick version ``10.9.2'' and {\bf Xcode} Version 5.1 (5B130a).
+The later Xcode (6.+) versions were tried but at the time of preparing this distribution
+were unstable and crashing.
+Possiblely now Xcode's latest version is stable but for now i'm staying with this earlier Xcode version.
+Each {\bf makefile\_APPLE script per subfolder are up-todate}
+and can be run individually within their subfolder.
+There are equivalent scripts to the mentioned APPLE scripts within the various folders
+with suffix GNU or SOLARIS indicating the operating system supported.
+
+Their use are the same under each operating platform.
+For example to regenerate only the \Yacco2's library, run the following {\it bash} commands:\fbreak
+\ptindent{1) cd \Whereyacco2/library}
+\ptindent{2) make Genw -f makefile\_APPLE \# gen c++ code from w files}
+\ptindent{3) make Rlse -f makefile\_APPLE \# compile c++ code and create library}
+All other port scripts {\bf should be eye-balled} against each {\it makefile\_APPLE} script
+for any adjustments needed when
+compiling/linking re: \Cpp{} compiler and {\bf ld} libraries used: {\it pthread}, {\it \Cpp}.
+For the above example with the {\bf {\it Rlse}} parameter inputted, you will see it as a label within the bash script
+with its appropriate compile and create the library commands.
+These scripts are reasonably documented for your eyes and editing.\fbreak
+\fbreak
+{\bf Note:} the {\bf makefile\_APPLE} script can be modified to support an older {\bf Xcode}
+version. \Yacco2{} has been developed on Xcode versions from 3 and greater
+on Apple's ``Cat'' platforms.
+You'll have to adjust your script for the appropriate \Cpp{} compiler
+and \Cpp{} runtime support library.
+
+@*2 Grammar Testsuite.\fbreak
+Added to the distribution in folder {\bf \Whereyacco2/grammar-testsuite} are some grammars
+from published papers
+testing out lr(0), lr(1), and lalr ness by running its ``test-out-grammars.sh’’ {\it bash} script.
+All platform scripts run \O2{} against the testsuite to
+confirm the distribution validity.
+It also runs self against self with one of its own grammars: ``eol.lex''.
+
+@*3 A translator for your learnings from the Grammar Testsuite.\fbreak
+To confirm that the distribution works, one of the published grammars: ``pager\_1.lex'' has a translator {\it {testout}}
+that is compiled, linked against the built \Yacco2{} library, and run against some input with
+some trace parameters turned on: see {\bf {1lrtracings.log}}.
+Have a peek in its folder to see how easy it is to build a
+compiler/translator: script makefile\_testout\_APPLE..
+Of course my leanings are towards ``literate programming'' use and hence the slant on its residues
+of generated documents.
+
+@*2 Quality Assurance.\fbreak
+In {\bf {\Whereyacco2/qa}} folder, there are a series of batch files that tests
+out the ``quality assurance'' of \Yacco2.
+Within the various tests are more grammars testing lr(1) compliance.
+For the curious or doubters have a look or try them out yourself.
+They might leave bite marks but should be a bit more convincing than my verbage.\fbreak
+\ptindent{{\bf{cd \Whereyacco2/qa}}}
+\ptindent{{\bf{ls *sh}} \# list of bash scripts to be run}
+
+@*1 Challenge to the Open Source / Computer Science Community.\fbreak
+Depending on the \Cpp{} code, {\it cweave} emits unstructured code.
+In the {\bf o2book} document there is a footnote as to why this is occuring.
+I raise the challenge to u to correct this in improvements to the ``Open Source'' evolution.
+
+Internet donations is a newer money raising model helping not-for-profit foundations
+with support staff
+but for the majority of Open Source projects, their life expectancy becomes short lived
+when others don't pick up the torch towards bug corrections etc.
+Letting the author ``just do it'' leads to a no-growth attitude for the next generation.
+Enough Dave of your squawking!
+So is the challenge taken up from possibly the computer science students as a class assignment?
+Let's hope the future tales whisper challenge accepted/taken/completed!
+
+@*1 Unix {\it{man}}'s quick overview to \Yacco2's programs and API.\fbreak
+In {\bf{\Whereyacco2/bin/man/man1}} are the Unix style references for:\fbreak
+\ptindent{{\it{o2}} compiler/compiler}
+\ptindent{{\it{o2linker}} \Yacco2's linker}
+\ptindent{{\it{yacco2}} API/library}
+Either set up a link to this folder in your startup file like {\bf{.bash\_profile}} to exercise them,
+explicitly reference their path when running {\it{man}}, or adjust your {\bf{/private/etc/man.conf}} file.\fbreak
+\fbreak
+Command-line-interface examples for \Yacco2's references.\fbreak
+The examples show variations
+ depending on how u set up the path reference:\fbreak
+\ptindent{{\it{man}} \Whereyacco2/bin/man/man1/yacco2.1 \#explicit reference to API library}
+\ptindent{{\it{man}} -M \Whereyacco2/bin/man/man1: yacco2 \# use man's path list}
+\ptindent{{\it{man}} o2linker \# o2linker and man.conf file has \Yacco2's reference's link}
+\ptindent{{\it{man}} o2 \# o2 where MANPATH has link}
+
+
+@*1 Documents to read --- U have edocs Sir!.\fbreak
+All docs are in the ``\Whereyacco2/docs'' folder in ``pdf'' format.\fbreak
+\ptindent{1) Grammars in their published format --- examples of literate programming using \Cweb}
+\ptindent{2) \O2's grammars in \Whereyacco2/compiler/grammars/*.lex in raw form.}
+\ptindent{3) \O2{} and \O2linker{} documented source programs.}
+\ptindent{4) wlibrary --- \Yacco2's documented library.}
+\ptindent{5) Some unpublished essays --- p1, p2 discussing the why of \O2's language paradigm.}
+\INDENT{1in}{Relatively relevent though early in \O2's development cycle.}
+\ptindent{6) Unpublished Tugboat-o2 essay on ``literate programming'' as applied to \O2. A must read.}
+\ptindent{7) Draft copy of reference ``o2book.pdf'' to rev u up.}
+\ptindent{8) ``testout.pdf'' and grammars ``test*.pdf, pager\_1.pdf'' comments on writing your own compiler.}
+\ptindent{9) ``testdriver.pdf'' and ``test\_components.pdf'' --- lexical quality assurance testing.}
+\ptindent{10) possiblely published book --- ``\Yacco2 and some practical uses''.}
+
+The unpublished essayes listed above should be read first as
+they describe in a light way the Why of \O2. For those that don't have time, at least speed read the
+``Tugboat-o2'' essay.
+{\it {testout}} program documentation should be read along with the ``o2book''.
+There are comments to developing your own compiler regarding the Terminal / Error Vocabulary, and
+Error tracing.
+At least there are some clues/comments/references to \Yacco2{}, and its use.
+
+``\Yacco2 and some practical uses...'' will be a ``how to'' set of observations/steps when i developed
+a retargetting Pascal translator. It deals with observations made in grammars evolution, Terminal/Error Vocabulary
+development, symbol table management controlled from grammars' logic points, to
+tree building and their walkings within semantic routines.
+The project's post evaluation gives observations, mistakes made, and potential
+warnings for your future language development.
+Hopefully to u a necessary companion with \Yacco2's reference ``o2book''.
+
+@*1 Comments: Typesetting, ``Literate programming'', and Drawing.\fbreak
+The principle software driving the typesetting
+of documents is \TeX{} which should be on your system.
+Metapost is the graphics drawing system used to sketch grammars.
+By combining the 2 components: \Cpp{} code and typesetting directives into one file, u now have
+a ``Literate program''. This is the principle used by \O2's grammars.
+\O2{} emits its own \Cpp{} code files.
+For its grammar documents, \O2{} maps the grammar into a \Cweb's template form called
+ a ``literate grammar''
+ and also emits Metapost grammar type files.
+These become the fodder for \Cweb's {\it cweave} program and Metapost's {\it mpost} digestion.
+The \TeX{} {\it pdftex} program turns their outputed files into a pdf document.
+All said, to use \O2{} does not require \TeX, \Cweb{} or Metapost systems to be installed but you are losing
+out on one of the gems in \O2's tiarra: document generation.\fbreak
+\fbreak
+{\bf Caveat}: as the \Cweb{} system is required to emit \Cpp{} code from ``Literate programs'', all
+of \Yacco2's programs and API library will be very difficult to modify/correct/enhance without this system installed.
+\fbreak
+
+Please go visit the {\bf {`www.tug.org'}} website.
+It provides ``downloads'' for various operating platforms of \TeX{}, \Cweb{}, and Metapost systems.
+Other interesting software gems are there for download.
+Accompanying these downloads are their ``How to use it'' manuals/documents.
+{\bf Please consider joining Tug} as there are a lot of ``Open Source projects'' that need your support
+to keep improving.\fbreak
+A recap on programs use:\fbreak
+\ptindent{1) {\it cweave} creates a ``.tex'' file from a ``.w'' program for document creation.}
+\ptindent{2) {\it pdftex} generates a pdf document from cweave's outputted `.tex' file.}
+\ptindent{3) {\it ctangle} generates the \Cpp{} program from the same `.w' program.}
+\ptindent{4) {\it mpost} is used to draw the grammar's productions generated from \O2.}
+\fbreak
+All \Yacco2's grammars and programs can be regenerated using these above programs.
+To generate the grammars's documents, they are run thru \O2 with the `-p' parameter
+that generates a `.w' file and accompanying mpost grammar diagrams for
+{\it mpost} and {\it cweave} digestion outputting the ``.tex'' file
+for {\it pdftex} to generate a ``pdf'' document.
+Running \O2{} without or with possible parameters ``-t'', ``-err'' generates
+the ``.cpp'' files
+to be compiled by your \Cpp{} compiler.
+\fbreak
+
+@*2 Bash/batch files to help u do the dirty work.\fbreak
+Have a look at `{\bf{o2grammars.sh}}’ bash script in `\Whereyacco2/compiler/grammars/'
+folder showing ``how to'' generate either a \Cpp{} or typeset document for each grammar.
+`{\bf{gen1grammar.sh}}’ bash script has the same capability but is applied to 1 interactively selected grammar.\fbreak
+Here's how to gen your grammars.\fbreak
+\ptindent{{\bf{cd /xxx}} \# your folder containing your grammar *.lex files}
+\ptindent{{\bf{. \Whereyacco2{}/compiler/grammars/o2grammars.sh Rlse}} \# gen c++ code}
+\ptindent{{\bf{cd /xxx}} \# your folder containing your grammar *.lex files}
+\ptindent{{\bf{. \Whereyacco2{}/compiler/grammars/o2grammars.sh Genw}} \# gen grammar docs}
+\ptindent{{\bf{mv *.pdf /xxx/docs}} \# optional: move docs from your grammars folder into your docs folder}
+
+@*1 Potential problems installing \O2.\fbreak
+This is a list of possible problems u might run across.
+As the system gets more exposure / use, this list will probably grow.
+Hopefully not too fast!
+
+@*2 Why is \Yacco2{} installed at the /usr/local level?.\fbreak
+My 1st virtual attempt to get \Yacco2{} out to the ``Open Source Community'' and my laziness
+had it installed at the root level but this has been changed.
+``/usr/local'' was chosen as this seems to be the crowd's concensus to installing foreign
+software.
+I contemplated using Apple's ``Framwork'' approach but this seems
+to be local to Apple though appropriate.
+The original include statements for \Yacco2's library and API have been adjusted.
+
+@*2 File Permissions.\fbreak
+After u installed the \Whereyacco2 folder make sure u can read / modify its contents.
+chmod utility might be needed or by running the script suffixed to the sudo utility.\fbreak
+\ptindent{{\bf{chmod +a "staff allow read" \Whereyacco2}}}
+ or \fbreak
+\ptindent{{\bf{sudo chmod +a "staff allow read" \Whereyacco2}}}
+ or \fbreak
+\ptindent{{\bf{sudo chmod 755 \Whereyacco2}}}
+
+
+
+@*2 Comments on compiling, linking, and \Cweb{} line macro referencing file's ``w'' code lines.\fbreak
+Files makefile\_* like {\bf makefile\_APPLE} or {\bf makefile\_GNU} are found in \Whereyacco2's subfolders
+ of ``compiler/grammars/, compiler/o2/,
+library/, or o2linker/'' that compile the individual \Cpp{} programs and possibly build a
+library, or create a runable program.
+These {\it bash} scripts are Unix flavoured.
+Cast your eyes on some of these files as the appropriate {\it bash} statements with comments
+ show ``how to'' roll your own within these various Operating system contexts.
+U should note the {\bf \Cpp's compiler options used}, and ditto
+on the {\bf linker's parameters}.
+They will clue u into what i needed to bootstrap \Yacco2{} onto
+different Operating system platforms.
+
+In some of the subfolders you will find a {\it bash} script ``{\bf makefile\_Edit\_CWEB}'' to comment out
+links to the CWEB code lines in the \Cpp{} generated programs.
+This is helpfull when u want to debug, set break points
+to the \Cpp{} lines of code rather than the ``.w'' line of code
+using your interactive debugger.
+Possibly the newer version of CWEB's {\bf ctangle} program has
+an option whether to emit the ``c'' line macro or not. My version does not.
+Hence the
+reason for the script to ``post process'' {\it ctangle}'s emitted C++ code.
+
+@*2 Where's libstdc$++$ or libc$++$ library?.\fbreak
+{\bf Note}: The below points also apply to the other computer scripts: SOLARIS and GNU.\fbreak
+
+
+These comments are more appropriate for older Xcode environments and other
+Unix platforms.
+One problem u might experience is where does the libstdc$++$ library reside
+for building both programs \O2{} and \O2linker{} if u are
+not using a development framework.
+Or possibly u might want to use a different \Cpp{} compiler/set of libraries then the one
+your system defaults to.
+For an Apple computer, {\it bash} scripts ``{\bf \Whereyacco2/compiler/o2/makefile\_APPLE}''
+and ``{\bf \Whereyacco2/o2linker/makefile\_APPLE}''
+might need editing along with the c$++$ compiler to be used due to your older
+Xcode environment: eg. g$++$ or gcc compiler and libstdc$++$ library.
+Find out where the libstdc$++$ resides on your system.
+Running these below {\it bash} commands to look for libstdc$++$ should
+find it. For other \Cpp{} library, run the same commands below
+with the appropriate library name to be searched:\fbreak
+\ptindent{{\bf find /usr/ $\vert$ grep libstdc$++$}}
+Or more general:\fbreak
+\ptindent{{\bf find / $\vert$ grep libstdc$++$}}
+Once found using your text editor, adjust the {\bf STDCC\_dir} variable
+with the found library location, the library {\bf CC\_lib} variable,
+and compiler {\bf CC} variable
+in the above 2 script files. The scripts are commented so u should not have any touble
+editing them.
+Now rerun the {\it bash} script to rebuild \Yacco2:\fbreak
+\ptindent{{\bf . bld\_bash\_APPLE}}
+
+
+@*2 An inconvenience on getting the typesetting to work.\fbreak
+An apology due to this minor inconvenience: the ``{\bf cwebmac.tex}'' file might need to be modified
+so that the grammar's file listings can be included into their generated documents.\fbreak
+\fbreak
+{\bf{Warning:}} Try generating a grammar document to see if your system needs to be adjusted.\fbreak
+{\bf{Warning:}} The instructions are an example of what I had to do to get it working on my Apple laptop.\fbreak
+{\bf{Warning:}} I am not responsible if they do not work covered by the license terms.\fbreak
+\fbreak
+{\it{
+The below instructions are what I had to do to get it working on my Apple laptop.\fbreak
+Please make appropriate backups before trying these instructions on your computer if required.
+}}
+\fbreak
+\fbreak
+To do this, u must find where the {\bf .../eplain/eplain.tex} file is
+installed on your computer from the Tex{} installation.
+In my computer, it is in the folder ``{\bf /usr/local/texlive/2014/texmf-dist/tex/eplain/eplain.tex}''
+where the year of the distribution in this example is 2014
+which u would substitute with your own distribution year.
+Possibly non Apple platforms could be distributed differently and would require you to use
+{\bf{its folder name instead of this example}}.
+Then u must edit ``{\bf .../cweb/cwebmac.tex}'' file from
+the \Cweb{} installation with the following
+line added at the beginning of this file:\fbreak
+\ptindent{{\bf$\backslash$input /usr/local/texlive/2014/texmf-dist/tex/eplain/eplain}}
+On my computer this file is found here:\fbreak
+\ptindent{{\bf /usr/local/texlive/2014/texmf-dist/tex/plain/cweb/cwebmac.tex}}
+U can use your prefered text editor but make sure u have write permission to this read-only file.
+I used vim text editor with sudo to obtain write privileges.\fbreak
+\ptindent{{\bf sudo vim /usr/local/texlive/2014/texmf-dist/tex/plain/cweb/cwebmac.tex}}
+Here are its edited contents with my \TeX{}'s \% comments:\fbreak
+\ptindent{{\bf \%\%\% Date: 23 Oct 2014 EDT modified cwebmac.tex file to fetch eplain tex macros}}
+\ptindent{{\bf \%\%\% needed is the $\backslash$listing tex macro to generate grammar documents}}
+\ptindent{{\bf $\backslash$input /usr/local/texlive/2014/texmf-dist/tex/eplain/eplain}}
+\fbreak
+
+@*1 Happy \Yacco2{}ing.\fbreak
+Bonne chance with your language development and use of \Yacco2.
+
+@** Index.