From: Jim M. <jam@McQuil.com> - 2004-10-20 18:00:12
|
Pierre, I'll answer your questions below. On Tue, 19 Oct 2004, Pierre Yann Baco wrote: > Hi! > > Here is a summary of my remarks-notes on LTSP 4.1 documentation while > translating it in french. > > I=B0) SGML tags warnings-errors trying to generate doc files from origina= l > en(glish) 4.1 doc file. Output of make: > > [yann@blue ltspdocs]$ make > Running jade > jade -t sgml \ > -V nochunks \ > -d /usr/share/sgml/docbook/dsssl-stylesheets-1.78/html/ltsp.dsl > \ > -c /usr/share/sgml/docbook/sgml-dtd-4.1/catalog > \ > ltsp-4.1-en.sgml >ltsp-4.1-en.tmp 2>openjade.stderr || \ > (cat openjade.stderr; exit 1) > jade:ltsp-4.1-en.sgml:621:18:E: end tag for "LISTITEM" omitted, but > OMITTAG NO was specified > jade:ltsp-4.1-en.sgml:619:6: start tag was here > jade:ltsp-4.1-en.sgml:1573:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1574:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1573:12: start tag was here > jade:ltsp-4.1-en.sgml:1574:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1570:12: start tag was here > jade:ltsp-4.1-en.sgml:1579:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1580:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1579:12: start tag was here > jade:ltsp-4.1-en.sgml:1580:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1576:12: start tag was here > jade:ltsp-4.1-en.sgml:1585:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1586:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1585:12: start tag was here > jade:ltsp-4.1-en.sgml:1586:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1582:12: start tag was here > jade:ltsp-4.1-en.sgml:1591:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1592:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1591:12: start tag was here > jade:ltsp-4.1-en.sgml:1592:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1588:12: start tag was here > jade:ltsp-4.1-en.sgml:1608:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1609:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1608:12: start tag was here > jade:ltsp-4.1-en.sgml:1609:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1600:12: start tag was here > jade:ltsp-4.1-en.sgml:1614:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1615:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1614:12: start tag was here > jade:ltsp-4.1-en.sgml:1615:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1611:12: start tag was here > jade:ltsp-4.1-en.sgml:1620:17:E: document type does not allow element > "PARA" here; missing one of "FOOTNOTE", "CAUTION", "IMPORTANT", "NOTE", > "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag > jade:ltsp-4.1-en.sgml:1621:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1620:12: start tag was here > jade:ltsp-4.1-en.sgml:1621:20:E: end tag for "PARA" omitted, but OMITTAG > NO was specified > jade:ltsp-4.1-en.sgml:1617:12: start tag was here > make: *** [ltsp-4.1-en.tmp] Erreur 1 > rm ltsp-4.1-en.tmp > [yann@blue ltspdocs]$ > > =3D=3D> All errors-warning fixed adding or moving end tags to the right p= lace. David is going to look more closely at the above problems. It doesn't happen that way for me. > > Remark: Many sections contain paragraphs, usually separated by a blank li= ne. > But the last paragraph of a section is NOT separated from the beginning o= f the > next section or list by a blank line. That's not really "nice". Examples = in > items 17, 20,23,24,25 and 26 of Section 1.1. Anything we can do ? Are you talking about HTML, PDF or Postscript output ? All 3 look fine for me. Maybe you are using a different version of htmldoc? I've seen that do funny things. > > > II=B0) References to previous versions in 4.1 documentation + some remark= s. > > a) Section 2.4.1 (/etc/dhcpd.conf): the standard 4.1 package comes with a > single 2.4.24 kernel, while doc contains refs to vmlinuz-2.4.9-ltsp-5 and > vmlinuz-2.4.9-ltsp-lpp-5. yes, should be fixed. Probably should make mention that whatever kernel we show in the docs is for example only. That there might be other versions of the kernel actually available. > > b) Section 2.4.3 (lts.conf): about the XSERVER paramater values: referenc= es to > XFree86 4.1 and XFree86 3.3.6, while 4.1 uses Xorg. Yep, Between LTSP 4.0 and 4.1, we upgraded to Xorg, but didn't update the docs. it needs to be fixed. > > c) Section 3.2.2 (choosing an etherboot driver for PCI cards). IMHO, the > given example is a bit obscure. Looks like user has to guess 8086 is Inte= l's > PCI ID and 1229 the EtherExpress PCI ID. I'm sure James knows all IDs by > heart, but what about proposing "lspci -v" to get the information, and a= link > to a web page showing a list of vendors and boards PCI IDs ? Actually, quite a bit of documentation could be written about this. You can't just run 'lspci -v', unless you've booted a full Linux. Either from harddisk or knoppix cd. Lots could be said, to clear it up. > > d) Section 5.2 (server side setup for printing). > - What about CUPS instead of printconf ? CUPS is widely used now. We should show CUPS configuration screens. > - The JetDirect example (fig 5.2) is an exception. What about using "stra= ight" > LPD ? Most LTSP users install cheap inkjet printers on workstations... Some confusion here. the LTSP terminal emulates a JetDirect interface. that doesn't mean that ONLY a jetdirect printer will work. Any printer, serial, parallel or USB should work. But to CUPS or LPRng, it should be configured as though the interface is jetDirect. > > e) Section 6. Screen scripts. > - I suggest to add a sample script to start ssh. there is no ssh screen script. that involves public and private keys, and other things that haven't been done yet. We can't just whip it up for the documentation. better docs of the shell, telnet, startx, and rdesktop scripts is needed tho. AND, some notes about how to write a screen script. > > f) Section 7.2.2 Is dhcpd running ? Documentation describes the ntsysv to= ol to > configure dhcpd to start at boot. What about chkconfig ? chkconfig for redhat, update-rc.d for debian rc-update for gentoo ? for Suse All of those should be shown. > > g) Section 7.4.3.1. NFS Daemon problems. Same suggestion (chkconfig inste= ad of > ntsysv) Same as previous answer. > > h) Section 7.6.1. (about XDM problems). Documentation contains a ref to > "ltsp_initialize". Should be ltspcfg / lstpadmin now ? Definately, this should be fixed. > > i) Chapter 8. Kernels. As 4.1 comes with 2.4.24 kernel(s), examples shoul= d be > updated accordingly. And I'm not sure 2.4.24 needs the NFS patch now. yes, 2.4.24 does need the nfs-swap patch. And rather than document a specific kernel, it should be made clear that the version of the kernel they are using may not exactly match the documentation. I don't think it is practical to update the docs everytime we release a new kernel. > > f) Several references to more-than-2-years-old Redhat distros. What about > Fedora and/or Mandrake (don't forger I'm french!). Anything to say to Deb= ian > users ? LTSP is mostly developed on Debian these days. Certainly we could do better at showing other distros. > > g) 2. Copyright and License. Reference to the GNU-FDL "which is hereby > incorporated by reference". Hard to translate for me. Does this mean "wel= l, > I'm talking HERE about the GNU-FDL, get a copy of it elswhere", or (as I > think) "This doc is released under the GNU-FDL terms, and here is a copy = of > it, included there (appendix)." Well, in that case, where is the appendix= ? > Btw, I won't translate the GNU-FDL. Hmm, I think we should just include a URL to the fdl license. > > That's all for now. Stay tuned. Comments - remarks - critics welcome! Thanks, great work, and we appreciate it. Jim. > > Pierre > > > > > > ------------------------------------------------------- > This SF.net email is sponsored by: IT Product Guide on ITManagersJournal > Use IT products in your business? Tell us what you think of them. Give us > Your Opinions, Get Free ThinkGeek Gift Certificates! Click to find out mo= re > http://productguide.itmanagersjournal.com/guidepromo.tmpl > _______________________________________________ > LTSP-Translations mailing list > LTS...@li... > https://lists.sourceforge.net/lists/listinfo/ltsp-translations > |