Document all options #38
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Opened 6 years ago
Last modified 3 years ago
#1677assignedtask
Document all options
Reported by:zzzOwned by:sadie
Priority:
minor
Milestone:
eventually
Component:
www/i2p
Version:
0.9.22
Keywords:
docs
Cc:
slumlord
Parent Tickets:
Sensitive:
no
Description
Perennial request
Some attempts and proposals:
http://echelon.i2p/docs/advanced.options.txt
Similar effort for rate stats: http://i2p-projekt.i2p/en/misc/ratestats
str4d proposed extending Properties and our utils to preserve comment lines when reading/saving, sounds hard
We could pull them out of the javadocs somehow
My theory was always that you don't need a list, you should just find the docs for what you want to do, but everybody loves a list.
However we format the results, first we need the descriptions for each.
See below for my list.
Subtickets
comment:9 Changed 3 years ago by zzz
Cc:slumlord added
Owner:
set to _sadie_Status:open →
assigned
reassigning to sadie for guidance and priority setting
cc: slumlord
comment:8 Changed 5 years ago by zzz
Attached patch takes a config file of descriptions, and merges it with the config when writing out. Not coded: merging for display on /configadvanced. This is rougly the 'alternative' proposed in comment 5 above.
Sample line from router.help.config:
Sample lines from router.config after a save:
This solution does not preserve comments when reading in a config file. They are remerged from the router.help.config file on every write.
Not sure how much I like this solution, so posting for discussion.
Changed 5 years ago by zzz
Attachment:config.diff
added
prelim. patch for review
comment:7 Changed 5 years ago by str4d
Status:new →
open
comment:6 in reply to: 5 Changed 6 years ago by str4d
Replying to zzz:
It was written for Java 1.4 :P The original author did say he would implement it differently now.
It would be an improvement, at least.
Easy enough: define
#foo=barexplicitly as a commented-out parameter, and# foo...as a real comment (which is in keeping with many other config file conventions). Then the reader can look for commented-out parameters and uncomment them when settings are changed in the routerconsole.Another alternative would be to leverage Commons Configuration, a self-contained 360kB JAR that would handle all of the above issues for us with a `Properties`-like object. It unfortunately can't be cast to a
Properties, but for router.config the router converts to aMapanyway, so you'd just do the same here.If we wanted to use Commons Configuration in other config files, more extensive patching would be necessary to convert from
PropertiesConfigurationtoProperties, but not unreasonable.comment:5follow-up: 6 Changed 6 years ago by zzz
Not too impressed with that code, except perhaps as inspiration. (Vector? ick)
We can, of course, include a default router.config with documentation, whether or not we do anything else. Without comment-preserving code, the comments wouldn't survive in the .i2p file but they would be found in the $I2P (i.e. reference) file.
Another alternative:
We don't preserve comments in the config file, but we do have a hardcoded table (or descriptor file) of descriptions for each key. When writing out the file, we just spit out any description we find for a key as a comment line before we write out the key. Then spit out all the other descriptions at the end.
This doesn't preserve user-generated comments, but maybe that's not so important.
As you noted above, Router doesn't even save the Properties returned from DataHelper?.loadProps() (see readConfig()), because a ConcurrentHashMap? is so much nicer than an unsynchronized Properties to store things in.
One problem that all of these solutions have is that you want to bind comments to a key=value line, so they live and die together. But that fails with a comment style like:
But if we uncomment the 'foo=false' line in the default config file, then we can't change the default in our code, so that's bad too.
Keeping all the comments in memory also sounds icky. Maybe just a read-before-write is sufficient, to store the comments only briefly.
Not yet convinced a coding solution is necessary or cleanly doable.
comment:4 in reply to: description Changed 6 years ago by str4d
Replying to zzz:
I found this nice implementation: http://www.dreamincode.net/forums/topic/53734-java-code-to-modify-properties-file-and-preserve-comments/page__p__874511&#entry874511
It wouldn't be directly usable, but could be adapted for our needs. Supporting persistent comments in
router.configwould require modifications toDataHelper.loadProps()andDataHelper.saveProps(), andRouterwould need to store aCommentedPropertiesthat could be updated on save instead of dynamically generating anOrderedProperties. (This could be done by overridingputAllto check if a property already exists, and if not then add it as a new line at the end of the file, possibly with a descriptive comment.)Docs can be hard to find, if you don't know what to search for. The prevalence of documentation in config files also means that many server ops look there first for common settings. More than that, server ops (at least those I have talked to about I2P's config) like being able to format their config file how they want, and have it stay that way.
If config files did support comments and kept their state, then we could have the installer include a default
router.configwith common options and their documentation. We should still have all options documented on the website, however.comment:3 Changed 6 years ago by zzz
Note that the general config file format, and some files (clients.config, logger.config, i2ptunnel.config) are documented here:
http://i2p-projekt.i2p/en/docs/spec/configuration
Any router.config documentation should be linked from there.
comment:2 Changed 6 years ago by zzz
Keywords:docs added
And the output:
Last edited 6 years ago
by zzz
( previous)
( diff)
comment:1 Changed 6 years ago by zzz
My list generator for core, router, console, and streaming. I2PTunnel not included, those generally don't apply to router.config. The list is pretty good, but it misses anything not declared as PROP_foo.
Last edited 6 years ago
by zzz
( previous)
( diff)