Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 6 Apr 2000 09:57:01 +0100
From:      Nik Clayton <nik@freebsd.org>
To:        stable@freebsd.org
Subject:   Task for -doc newbie / XML'ing LINT. . .
Message-ID:  <20000406095701.C62492@catkin.nothing-going-on.org>

next in thread | raw e-mail | index | archive | help
Hi,

[ sent to -doc, where it's on topic.

  Sent to -stable, where there's been much discussion of the docs
  recently.  If anyone's got any energy left from that they could usefully
  expend it on this.

  Sent to -hackers, where the last chunk about XML is on topic, and will
  probably get me lynched. . .
     
  Follow-ups *not* set, as depending on which bits you reply to might
  make it more appropriate for one list or another. ]

If anyone's looking for a relatively simple, but quite involving task. . .

Update section 2.3 of the Handbook, "Supported Hardware".  In particular,
for each piece of hardware I'd like to know

  * The name of the hardware (which we already have, pretty much)

  * The category ("Disk Controller", "NIC", "USB", "ISDN", "Serial",
    "Mice", "Scanners", Other. . .)

  * The name of the driver/kernel config entry it's associated with

  * A URL for a page on the manufacturer's website that describes the
    product (if it exists).

  * Other URLs of interest (for example, if someone else has a page up
    that explains how to use this device with FreeBSD).

  * Assorted notes about the product

What would be particularly useful is if we can get this information in
a queryable form (XML, rah rah rah).  We could then

  * Convert it to DocBook for inclusion in the Handbook

  * Build something much like the BSDI's website "Supported Hardware"
    section, where you can search for your hardware, and it gives you
    back lots of info about the device.

[ OK, I'm pushing the boat out big time on this one, and it'll probably
  get shot down, but what the hell ]

  * Use this as *documentation in the source tree* to build chunks of
    the LINT config file.

    Imagine, for example, src/sys/pci/DRIVERS.xml, which looked something
    like (and I'm doodling on the back of an envelope at the moment)

      <controller>
        <type>pci</type>

        <device>
          <type>NIC</type>
          <name>fxp</name>
          <descr>EtherExpress Pro/10, Pro/100B, Pro/100+ Fast Ethernet
            adapters, based on the Intel i82557 or i82559
            chipsets.</descr>
        </device>

        <device>
          [ ... ]
        </device>

        <option>
          <name>PCI_QUIET</name>
          <descr>quiets PCI code on chipset settings</descr>
        </option>
      </controller>

    LINT would then become some boiler plate text for things we don't
    want to describe this way, plus the output of a process which takes
    the above and turns it into a config(8) style file.

    When you add a new driver, update the .xml file(s) as necessary.  Next
    time LINT is built it contains the appropriate text, next time the
    Handbook is built it lists the device as supported. . .

Thoughts?

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000406095701.C62492>