Rename fields to make the names more meaningful

[gildor478]

This feature request has been migrated from artifact #703 on forge.ocamlcore.org. It was assigned to user102.

user188 posted on 2010-07-27 15:42:26:

For example, look at: ByteOpt

It could be something related to bytecode optimization. Or about bytecode compilation being optional.

My proposal is: BytecodeCompilatonOptions

or maybe ByteCompOpts (personally I prefer the more readable version above).

user102 replied on 2010-07-27 15:55:58:

What about ByteOpts ?

You cannot mismatch it with optimization options.

user188 replied on 2010-07-27 16:21:46:

I like "ByteOpts" more than "ByteOpt". However it is missing any hint that it is related to compilation. Bytecode can be not only compiled, but also installed, executed...

There are more fields, whose meaning you have no chance to guess just looking at their identifiers.

According to my feelings they are: Categories (no idea even after careful reading of the whole documentation; I know it only after I found a corresponding entry in Cabal) FilesAB (some files... otherwise meaningless for me) Plugins (don't know what plugins? installed/required/compiled/related/exposed?) ByteOpt (missing "compilation" and unclear "options" pieces of information) NativeOpt (as above) Type (misleading as "document type" while it stays for "plugin name")

Not bad, but could be improved: DataFiles (missing hint that it is about installation) Modules (say that it is about compilation) InternalModules (as above) XCustom (would like to know that it is a command)

Don't take me wrong, I like the OASIS system.

user102 replied on 2010-07-27 16:44:29:

Don't take me wrong, I like the OASIS system.* -> not at all, you help me to improve it. I like that.

I am not sure to want to change the name of these fields. Unfortunately, you have to make a choice between field name length and meaning. It is quite hard to choose. Some people will like to use very short name, esp when you begin, but with time, you will want to use shorter name. But I can propose more meaningful help, which will not add more length and will improve understanding.

Here are the modified help I can propose:

Categories -> well, it is not clearly defined because I don't know precisely what I want to put here. I will probably copy the topics from the hump. See topics here http://caml.inria.fr/cgi-bin/hump.fr.cgi?sort=0&browse=4

FilesAB: Files to generate using environment variable substitution. What about: Files generated after the configure step, using variables defined at this moment.

Plugins: Extra plugins to use. OK, this is a list of extra plugins to apply like META or StdFiles. What about: Extra plugins to generate files, like META with the plugin META and README.txt with the plugin StdFiles.

ByteOpt: ocamlc arguments to use when building. What about: arguments added to 'ocamlc' invocation during compilation.

Same for NativeOpt.

Type for Document -> Builder Type for Test -> Runner

DataFiles: Comma separated list of files to be installed for run-time. (see here) I don't see what is missing here.

Modules: List of modules to compile. InternalModules: List of modules to compile which are not exported. I don't see what is missing here either.

XCustom: Run command to build documentation. Maybe

user188 replied on 2010-07-27 22:26:07:

So, we have two separate things: identifiers and documentation. Obviously, the more precise the documentation, the better. Many fields are already well explained e.g. I understand what DataFiles is.

But the problem with identifiers is a different thing. I understand that short forms seem more convenient than verbose ones. But the convenience is really insignificant compared to the importance of readability.

With short, cryptic identifiers you make OASIS for a narrow circle of insiders.

Verbose, clear and meaningful identifiers are inviting, friendly for newcomers. I believe that "mandatory RTFM" is a bad design smell.

Ideally, one would will look at some _oasis file and immediately understand most of it.

user102 replied on 2010-07-27 22:50:17:

Taking your first example: BytecodeCompilatonOptions is anyway too long and not significant to a beginner. This option is for advanced user. If you reach this question in quickstart, you must have set level to expert. CCopt, CCLib and other fall in the same level.

What I can propose to you is to focus on beginners fields. Someone claiming an intermediate or expert level should know a little more about what an RTFM is ;-)

I think the list for beginner is: Plugins: Extra plugins to use -> ??? Type for Document -> Builder (or BuiltType) ? Type for Test -> Runner (or RunType) ? Modules: List of modules to compile. -> ExportedModules ? InternalModules: List of modules to compile which are not exported. -> ???

Any suggestions for the "???" fields?