[rfc][icedtea-web]Localized Man Page Script
Jie Kang
jkang at redhat.com
Thu Jul 10 19:31:07 UTC 2014
Hello
I have modified the code a bit and added test cases in response to your suggestions. I have also created a OptionParser utility class to take care of parsing the arguments given to main(String[] args). A future patch will make use of this in other classes (such as Boot) in order to remove duplication. Feedback is appreciated!
----- Original Message -----
> On 06/26/2014 07:39 PM, Jie Kang wrote:
> > Hello,
> >
> > I've started working on a tiny bit of the implementation for the Java-based
> > Local Man Page Generator.
>
> Thank you for taking care of it and thank you for sharing thought so early.
> >
> > At the moment it lets you create man pages through main() by specifying
> > locale and name of man page.
>
> The class looks quite ok, but I'm not sure of it usefulness.
>
> Few nits to class itself
> * I would put all this work to package
> net.sourceforge.jnlp.resources....generator?util?manpages?infogenerator?
Okay.
> * I would not use private classes (non of the enums here have the right to
> be ) - and each public
I disagree a little bit. Traditonally, constants have been provided using 'static final Object'. However, enums were introduced in order to enhance and improve the way constants are defined in Java. The enums in this situation define constants for the class. I can agree that my implementation is not the very best but I would prefer enums over private static final objects.
As well, with the enums we can easily provide help messages for all of our modules (this work is in progress).
Alternatively we can define these enum constants in some public class so that all of ITW can use them. This prevents duplication which occurs in the code already.
E.g. If you look at MessageProperties.java in test-extensions/ : it basically has the same enum and some methods that my code could use, but is in test-extensions. As well there are other files such as JNLPRuntime that use constants for "Message.properties" and "net.sourceforge.jnlp.resources" so we can remove this duplication with public enum class. This fix should be a separate patch.
However, if you wish I can remove the enums and replace them with 'private static final' objects.
> member should have tests on each method ;)
I have added unit tests for the exposed methods.
>
> Well the usecase - I think that you do need this class at all.
>
> I believe, that before the generation, you can simply set LANG
>
> (
> LANGBACKUP=$LANG
> for E in "" ".UTF-8" ; do #some more encoding? Do we need to bother with
> encodings at all?
> for L in "" en_US$E pl_PL$E de_DE$E cs_CZ$E ; do #is "" wonted/needed?
> export LANG=$L
> java -CP=... net.sourceforge.jnlp.resources.some_main_in_subpackage
> -output={javaws|policieditor|itwsettings|icedtea-web} -outputDir=someDir
> done
> done
> LANG=$LANGBACKUP
> export LANG
> )
The current approach can be used very similar to the script you gave above. (I don't think we need to bother with encodings, subject to change but it is very easy to modify) It can work as follows:
for L in "" en_US$E pl_PL$E de_DE$E cs_CZ$E ; do
java -CP=... net.sourceforge.jnlp.resources.some_main_in_subpackage
-lang $L -name javaws policyeditor itw-settings icedtea-web #we can add outputDir argument if necessary, but we should be able to generate it based off $L and $M
>
> and use JNLPRuntime + Translator to get correct messages.
>
Using the JNLPRuntime + Translator seems like a huge amount of extra overhead for what we need here. Using JNLPRuntime means JNLPRuntime being initialized multiple times. The JNLPRuntime initialization includes a lot of things we don't need for this generator so I don't think this is a good idea. Also setting LANG over and over is unnecessary when we can supply arguments to main().
> But this approach must be verified.
>
> Otherwise this will bring up duplicated code.
This is a very valid point for using JNLPRuntime. However, I think we can consider extracting a few methods from JNLPRuntime into something like a ResourceBundleManager (similar to how we OptionParser addition is an extraction from Boot) in order to reduce the duplication.
>
> Also I guess the correct location inside outputDir can be guessed from
> locale (or if it more simple
> to generate it from $L and $E then I probablky do not care)
>
>
> well my $0.02 :)
>
>
> > This is for during build process.
>
> Yes, thats correct. Build time is the place when this is supposed to happen.
>
> >
> >
> > It is attached. Jiri, could you look over it? I am still unsure if this is
> > the direction you want to go in.
>
> Thank you for keeping me in loop!
> >
> > ----- Original Message -----
> >> On 05/20/2014 09:53 PM, Andrew Azores wrote:
> >>> On 05/20/2014 03:52 PM, Jie Kang wrote:
> >>>> Hello,
> >>>>
> >>>> I've made all the suggested fixes and am working on the makefile at the
> >>>> moment.
> >>>>
> >>>> Thanks,
> >>>>
> >>>>
> >>>
> >>> Looks good to me. Please post the new patch when you have your script
> >>> integrated and tested working
> >>> in the Makefile.
> >>>
> >>> Thanks,
> >>>
> >>
> >>
> >> hi!
> >>
> >> The creepy voice from behind the sea have nasty words to say :(
> >>
> >> I'm afraid we ca not use this approach. And as it is it must not be
> >> pushed.
> >>
> >> The original idea of this feature was to *reuse* already existing,
> >> localized
> >> properties files.
> >> Also it was intended to share output between manpages *and* applications
> >> (javaws, policieditor,
> >> itw-settngs) --help option. Also maybe add icedtea-web manpage, and
> >> (probably) also have an
> >> possibility to generate more then man pages - eg html "man pages" or
> >> whatever.
> >>
> >> You can see that -help swihhc already provides eg full list of programs
> >> switches, or some about
> >> sntences....
> >>
> >> Well your approach do not implement any of this. Well, as opposite it
> >> file
> >> new file to localize
> >> and even more fiels to maintain.
> >>
> >> My original idea on this to have java based generator, included in netx
> >> itself.
> >> Its "main" class will be able to :
> >> - be called during the build (just put $CLASSES to CLASSPATH and invoke
> >> main)
> >> - generate man pages in reqested language
> >> - genreate html man pages (well I think there is some man2html, so
> >> maybe
> >> this is waste of
> >> everything)
> >> - the html files may save as base for help in gui modes
> >> - be called from javaws/itwsettings/policieditor and so
> >> - generate -help output
> >> - implementation detail - do not add "language swithc" generate files
> >> baed
> >> of currently set LOCALE
> >> - much more :)
> >>
> >> As benefit you will get
> >> - all the messages will come form properties
> >> - only properties to maintain!
> >> - parsing of properties in free - unicode support, and insertion of
> >> parametres from JDK itself
> >> - improved -help output (from man pages)
> >> - improved manpages form -help outputs
> >> - list of all switches
> >> - all default file locations!
> >> - get rid of about/help code from main classes of itw
> >> - much more;)
> >>
> >> If some messages are in man pages, but not in properties, you can add them
> >> into proeprties, but
> >> please verify that there is no similar in properties. And of course vice
> >> versa.
> >>
> >> Well most of http://icedtea.classpath.org/wiki/IcedTea-Web#Release_Plans
> >> since 1.3 are mostly
> >> somehow inserted by me. Sometime from need, sometimes from wish (feel free
> >> to
> >> add yours, or suggest
> >> modifications!) But pelase, always consult a bit before first patch.
> >> Mostly
> >> IRCis enough :)
> >>
> >> Sorry for this email:( But this is really stop show for this approach).
> >>
> >> Please try to post the patch ins small hunks, but it can be harder then
> >> write patch itself, andnot
> >> always possible, or meaningful.
> >> I hope I havenot forget something :( But we can tune it during the
> >> process.
> >> But I'm afraid nowyou
> >> are dammed to wait with final push on this topic to me returned from PTO
> >> :o)
> >>
> >> All the best!
> >> J
> >>
> >>
> >> Few notes to code itself just "education purposes":
> >> - changelog - the first line of changes should be caption. Eg "Added
> >> generator of man pages" for
> >> this particualr setthsi
> >>
> >> date-name-email
> >> [emtyline]
> >> [tab]caption
> >> [tab]* file:changes
> >>
> >>
> >> In changelog - always clearly say that it is new file. like
> >> [tab[ * file: new file, its purpose
> >>
> >>
> >> I'm not sure how good templates for man pages will be suitable in java
> >> based
> >> solution.. Well then
> >> may be. We will see. I hoped to have some class like "Content provider"
> >> which
> >> will use some class
> >> "markup" and together they will provide
> >> - context of desired verbosity
> >> - marked in markup you wont
> >>
> >> You can think about it as execise from some "system architecture" because
> >> it
> >> is isolated system in
> >> netx :) (whch you are designing from ground)
> >>
> >> In case of template - I would suggest %{key} rather then simple @KEY
> >> (although for your sh based
> >> solution @KEY is most correct)
> >>
> >> Otherwise splendid work on code, and sorry for wasting it:(
> >>
> >>
> >
>
>
Thanks,
--
Jie Kang
-------------- next part --------------
A non-text attachment was scrubbed...
Name: localmanscript-2.patch
Type: text/x-patch
Size: 21647 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/distro-pkg-dev/attachments/20140710/93b11e81/localmanscript-2-0001.patch>
More information about the distro-pkg-dev
mailing list