Devices Dumps Library improvements

[networkupstools]

Devices Dumps Library improvements

[zykh]

#94 (comment)

ddl repo

We may want to split things down to Manufacturer/Model_Families/Models:
https://github.com/zykh/nut-ddl-raw

pages

When we build the website, we could (easily) build asciidoc files starting from .dev files so that we can generate something like this:
https://github.com/zykh/nut-ddl

[zykh]

I forgot, what we may want to do with HCL:
https://github.com/zykh/nut-ddl/blob/master/hcl.adoc

[aquette]

@zykh: perfect!
the driver manpage link is something I want to have for years.

[zykh]

I started working on the DDL generation:
https://github.com/zykh/nut-website/tree/ddl

output (~6m): https://drive.google.com/file/d/0BxWv_9cok7BKVDA0RlQxUTVBOWs/edit?usp=sharing

It supports both old .dev/.seq files and the proof-of-concept .nds (NUT Device Simulation not Nintendo DS roms) ones.

See output's:

• ddl/index.html
• stable-hcl.html
• ddl/Manufacturer_Name/index.html
• ddl/Manufacturer_Name/Actual_Model.html (from .nds file)
• ddl/Eaton/index.html
• ddl/Eaton/Powerware_9130.html (from .dev file)
• ...

thoughts?

[zykh]

Added some devices dumps and updated ddl generation.
Same links as before:

• https://github.com/zykh/nut-website/tree/ddl
• output (~7m): https://drive.google.com/file/d/0BxWv_9cok7BKVDA0RlQxUTVBOWs/edit?usp=sharing

Thoughts? Rants?

[clepple]

Overall, looks nice. (I defer to @aquette for any potential deployment issues, since he manages the website.)

A few minor notes:

• the default font size makes the italic text hard to read (for the variable names).
• on the same topic, a table that matches the developer guide's list of variables (perhaps without borders) would align the values.
• Since some of the dumps are from old mailing list posts, we might want to have a mapping of old device names to their replacements. newhidups is the predecessor to usbhid-ups (ddl/MGE_UPS_SYSTEMS/Evolution_650.html), and eventually we might want to suggest that megatec and blazer_* upgrade to nutdrv_qx. ("This device may also work with driver XYZ...")
• Should we have a way to flag bad values? If the mailing list discussion mentions that certain values are not correctly reported, this might be a good place to indicate that. Maybe a specially-formatted end-of-line comment? e.g. #BAD: this value is too large by a factor of 10

Thank you for all of your work collecting this information! I should probably contribute a few myself.

[zykh]

Thanks for your feedback, Charles.

• moved from em to strong; added old->new/suggested drivers links:
  • https://github.com/zykh/nut-website/tree/ddl
  • output (~7m): https://drive.google.com/file/d/0BxWv_9cok7BKVDA0RlQxUTVBOWs/edit?usp=sharing
• here's a version with tables:
  • https://github.com/zykh/nut-website/tree/ddl-table
  • output (~7m): https://drive.google.com/file/d/0BxWv_9cok7BKM2c3R1JkXzNkNHc/edit?usp=sharing
• if we don't care about row borders, we can use instead a horizontal labeled list to align the values:
  • https://github.com/zykh/nut-website/tree/ddl-hll
  • output (~7m): https://drive.google.com/file/d/0BxWv_9cok7BKdS1vLWFldmJtam8/edit?usp=sharing

However, note that:

• using tables:
  • since asciidoc style (= a new call to asciidoc per cell) is required in RW/comments cells, it'll take some time more to produce the output;
  • we can't use tables with the same delimiter as the outer one (at the moment !) in comments and only one level of nested tables (using |)
• using horizontal labeled lists:
  • we can't use nested labeled lists in comments with the same delimiter (at the moment ;;), so are supported only labeled lists using the other ones (2-4 colons)

Note that, at the moment, although dummy-ups, relying on parseconf, simply ignores everything after a hash, there's no support in ddl generation for in-line comments since it would be hard to discern between vars value and comments, e.g.:

var.name.1: the UPS reports a #value# full of ###hashes # believe it or not, everything before the last hash is the actual value of the var
var.name.2: 123 # while this is a comment

This is not the case with a specific text like #BAD - just pointing it out.

Having said that, wouldn't it be a little redundant with var comments to support also text after #BAD?
We could use it just as an in-line flag so that we can add an attribute to that var's value:

var.name.1: bad value #BAD
var.name.2: another bad value#BAD

to asciidoc:

- *var.name.1*: [bad-value]+pass:specialcharacters[bad value ]+
- *var.name.2*: [bad-value]+pass:specialcharacters[another bad value ]+

that will add the bad-value class to the text and then we can style it to stand out (border/outline/background/...), e.g.:

span.bad-value {
    outline: red dashed .2em;
}

[aquette]

Hi Daniele

very briefly...

2014-04-08 0:53 GMT+02:00 Daniele Pezzini [email protected]:

Thanks for your feedback, Charles.

moved from em to strong; added old->new/suggested drivers links:
- https://github.com/zykh/nut-website/tree/ddl
- output (~7m):
https://drive.google.com/file/d/0BxWv_9cok7BKVDA0RlQxUTVBOWs/edit?usp=sharing
-

here's a version with tables:
- https://github.com/zykh/nut-website/tree/ddl-table
- output (~7m):
https://drive.google.com/file/d/0BxWv_9cok7BKM2c3R1JkXzNkNHc/edit?usp=sharing
-

if we don't care about row borders, we can use instead a horizontal
labeled list to align the values:
- https://github.com/zykh/nut-website/tree/ddl-hll
- output (~7m):
https://drive.google.com/file/d/0BxWv_9cok7BKdS1vLWFldmJtam8/edit?usp=sharing

However, note that:

using tables:
- since asciidoc style (= a new call to asciidoc per cell) is
required in RW/comments cells, it'll take some time more to produce the
output;
- we can't use tables with the same delimiter as the outer one (at
the moment !) in comments and only one level of nested tables
(using |)
-

using horizontal labeled lists:
- we can't use nested labeled lists in comments with the same
delimiter (at the moment ;;), so are supported only labeled lists
using the other ones (2-4 colons)

great!
I'm more for horizontal labeled list

thanks and cheers,
arno

[zykh]

added #BAD and #COMMENT end-of-line comments to the horizontal labeled list one:
https://github.com/zykh/nut-website/tree/ddl-hll
output (~7m): https://drive.google.com/file/d/0BxWv_9cok7BKdS1vLWFldmJtam8/edit?usp=sharing

[clepple]

@zykh nice! I still haven't gotten the Buildbot setup to automatically build this, but here is the latest revision: http://buildbot.networkupstools.org/~buildbot/cayman/docs/rdd3e89f08c4cd38b944921fad9789e537d21a889-27/ddl/

[aquette]

@zykh : very nice! Please go ahead and merge. I'm considering 2.7.3 for very soon. thx!

[zykh]

Rebased and with the ddl git module pointing to https://github.com/networkupstools/ddl : https://github.com/zykh/nut-website/tree/ddl_rebased

https://github.com/zykh/nut-ddl-raw should be transferred to https://github.com/networkupstools/ and renamed to ddl (if this is ok for you).
Apparently GitHub needs me to have admin rights to transfer it to the organization: can you create a temporary team with admin rights and add me to it?

[aquette]

@zykh: I've temporarily added you to the Owners team, so that you can proceed in moving zykh/nut-ddl-raw to networkupstools/nut-ddl.
Please ping me back when it's done.
I'm also in favor of 'nut-ddl' instead of simply 'ddl', for a better coherence with the other repos.
thanks for all your work Dan!

[zykh]

@aquette, done and updated nut-website repo

[clepple]

Looks good. Here's the BuildBot output: http://buildbot.networkupstools.org/~buildbot/cayman/docs/r6533a9f354006f702398bcd0cce2a0bf3f80881f-31/ddl/

[aquette]

code repository moved to https://github.com/networkupstools/nut-ddl

[clepple]

@aquette, this is the last issue on our list before releasing 2.7.3. Anything else we need to do here? Should we split any features off into separate issues?

[aquette]

@clepple: everything seems good. I've merged the other remaining PR for 2.7.3.
We can proceed to releasing 2.7.3. Anything else will wait for the next point release (2.7.4)

[aquette]

I think this ticket is good to be closed.
@clepple and @zykh : anything I missed?

[clepple]

Looks good to me. Since we have some old URLs at the beginning of this ticket, it should be mentioned that the final location is http://networkupstools.org/ddl/

[aquette]

@cleppe: thanks ;) I've updated the description to list the final locations, for both the website and the github repository. Now closing the ticket