Howdy! ( thats Texan for Hi for those that don't know ) For now this is the only documentation availible for this package. I hope to have this shortcomming fixed by the next release. ################################################################################ # NOTICE: This is a alpha code release so handle it acordingly. I do not believe # it will damage your system but you never know. This software will only write # to the current directory or the directory supplied on the command line for # the output file. It will open other files in read mode only. ################################################################################ # The software in this package is copyrighted 2000 (c) by Richard D. Jackson # # The software in this package is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. ################################################################################ This package contains two things a perl class called Pod::Lyx and a wraper for that class called pod2lyx. As the name implies this package will convert perl pod documentation into a format readable by LyX ( see http://www.lyx.org for information on LyX ). Why did I write this? ===================== I really wanted a good way to print pod documentation where I could control certin aspects of the process. I'm sure some of you are saying that their are already ways of doing this. True there are, but they didn't produce the results I wanted. And I have used LyX for various things in the past and thought to myself that I could get what I wanted out of LyX if I could just get the pod documentation into LyX. So I created this package to do the pod to LyX conversion stuff. Now I can use LyX to get the results I want. So I'm happy for now that is. This converter as it stands is lacking many things but it will do 80-90% of the work for me or you if you decide to use it. I do hope I will be able to get the converter to do more of the work later thus reducing the amount of time I/you have to spend tweeking little bits here and their to get the results I/we want. How to install the package? ============================ perl Makefile.PL make make install Thats it you are ready to go. How do I run this without installing it? ========================================= In the directory that you expanded the tar ball in do this: cp -R ./lib/Pod ./Pod cp ./scripts/pod2lyx ./pod2lyx You can now use pod2lyx without installing it. But you will need to be in the source directory or it will not work correctly. How do I use this thing? ========================= 1) You have a pod file in the current directory that you want to convert. pod2lyx podfile.pod pod2lxy perlwithpod.pl pod2lyx perlmodule.pm 2) You have a pod file in some directory that you want to convert. pod2lyx somedir/podfile.[whatever] 3) You want to convert a pod file shipped with Perl. pod2lyx perlpod # don't put an extention on pod documentation that # is distributed with perl. 4) You want to extract the pod documentation from an installed module or script. pod2lyx Pod::Lyx # note this will not produce any thing at this time # because Pod::Lyx does not contain any pod # documentation yet :( pod2lyx open # this will extract the pod documentation out of the # first open.* match. Other wise if you have installed # a open.pl and a open.pm and they both contain pod data # the first one found will be converted. NOTE: If you # were to have something like File/open.pm installed # this will not match because it is not at the same # level in the module tree. You would want to use # File::Open instead. 5) For now pod2lyx is quiet in that no error messages are output when it can't find the pod file it just exits :( Also no usage statment is printed to the teminal when you just type pod2lyx. This is one of the first things I will be adding for the next release. There are a couple of options that you can pass to pod2lyx that actualy work right now. inputfile the file to convert to LyX it must be on the command line before the outputfile name. outputfile The file name to use when writing the LyX file. By default the file will be named podfile.lyx for normal pod files. For class files or modules like Pod::Lyx it will be Pod_Lyx.lyx. -lyx_title="document title" use this to over ride the default tile. Currently the default title will be the pod file name or class name -lyx_indeex=0 A 0 means do not generate a index. The default 1 will generate a index. -lyx_tabstop=8 use this to over ride the default tab stop that is used when expanding tabs in verbatium text. perlpod states that the tab stop should be set to 8 but in reality most if not all pods use a tab stop of 4. The default is 4 because it works in most cases. Things that eather are not implemented or don't work as expected: 1) E is not converted. 2) C< soemthing B something > does not work correctly. The output will contain one to many spaces. 3) L<> For now I'm just outputing the contents of what is inside the link tag. Also their are some pod's that just don't quite look right when conveted to the LyX format. My ToDo list in order of priority: 1) Write better documentation 2) Fix pod2lyx so that error messages are reported to the user versas just exit. 3) Have pod2lyx display a usage screen 4) Work on creating links correctly. 5) Work on making those pod files that just don't look right look right. 6) Work on the C<> bug. 7) Implement handling of escapes in the pod file. 8) Look into putting a foot note on page one indicating the file name and version of the file/module used to generate the LyX file. This would let us know if we need to print a new copy when we update our software. Bugs: 1) I'm sure there are some of them but I ran out of Raid so I'll just have to deal with them as they come up. Contact: For now use my main mail account richardj@1gig.net. I do monitor the lyx-users list so if you post something their I will mostlikly find it. When sending me something please put pod2lyx in the header so I don't just delete it when I clean out my mail box. Also if you don't mind drop me a note if you find this usfull.