Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Gentoo: Doc

Getting rid of <codenote>

 

 

Gentoo doc RSS feed   Index | Next | Previous | View Threaded


neysx at gentoo

Apr 4, 2005, 8:01 AM

Post #1 of 7 (353 views)
Permalink
Getting rid of <codenote>

Hi all,

I suggest getting rid of <codenote> in GuideXML.
FYI, all it does is prepend '//' and behave just like <comment>
It was intended as a C/C++ comment, has bever been used for that but is always
used where a <comment> should be used instead.
"""
When you comment something inside a <pre> construct, only use <codenote> if
the content is a C or C++ code snippet. Otherwise, use <comment> and
parentheses. Also place the comment before the subject of the comment
"""
from http://www.gentoo.org/doc/en/xml-guide.xml#doc_chap3_pre4

Having two different tags for code comments is confusing, unnecessary and
leads to code samples where '//' is either meaningless or wrong.

Why we have a special tag for C/C++ comments is beyond me. It's never been
used and we have plenty of code comments that use <comment> and the proper
characters depending on the context, e.g. <comment># Bash comment</comment> or
<comment>&lt;!-- XML comment --&gt;</comment>

Only a few documents outside /doc will need to be fixed on their next commit:
./proj/en/base/amd64/howtos/2005.0-upgrade-amd64.xml
./proj/en/base/amd64/2005.0-upgrade-amd64.xml
./proj/en/desktop/x/x11/maintaining.xml
./proj/en/devrel/new-dev-training.xml
./proj/en/devrel/recruiters/mentor.xml
./proj/en/releng/catalyst/catalyst-howto.xml
./proj/en/infrastructure/config-syslog.xml
./proj/en/infrastructure/mirrors/config-rsync.xml
./proj/en/infrastructure/firewall/server-firewall.xml
./proj/en/infrastructure/mirrors-rsync.xml

I'll provide their owners with patches.

I can also fix all *valid* files under /doc, translations included (unless you
want me to leave them alone and let you do it):
./gentoo-security.xml
./guide-to-mutt.xml
./prelink-howto.xml
./ipv6.xml
./faq.xml
./new-upgrade-to-gentoo-1.4.xml
./ldap-howto.xml
./altinstall.xml
./gentoo-ppc-faq.xml
./guide-localization.xml
./ltsp.xml
./ati-faq.xml
./dri-howto.xml

guide.xsl will still handle <codenote>'s so that we do not have to fix a bunch
of old GWN's.


Any objections?


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\
Attachments: signature.asc (0.25 KB)


jan.kundrat at fzu

Apr 4, 2005, 10:21 AM

Post #2 of 7 (351 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

Xavier Neys wrote:
> guide.xsl will still handle <codenote>'s so that we do not have to fix a
> bunch of old GWN's.

So you'll have to maintain one useless language construct. Why not do
some sed-ing and avoid possible troubles in future - "hey, this tag is
neither documented nor used, let's remove it"...

If there's an easy way to get all the XML source files, I could create
patches :-).

-jkt

--
cd /local/pub && more beer > /dev/mouth
--
gentoo-doc [at] gentoo mailing list


neysx at gentoo

Apr 4, 2005, 11:44 AM

Post #3 of 7 (349 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

Jan Kundrát wrote:
> Xavier Neys wrote:
>
>>guide.xsl will still handle <codenote>'s so that we do not have to fix a
>>bunch of old GWN's.
>
> So you'll have to maintain one useless language construct. Why not do
> some sed-ing and avoid possible troubles in future - "hey, this tag is
> neither documented nor used, let's remove it"...
>
> If there's an easy way to get all the XML source files, I could create
> patches :-).

If all it took was s/codenote/comment/g, it would be trivial and I would not
even suggest leaving it in guide.xsl. FYI, it only takes a few lines right
before the bit that handles <comment>. It really does not cost anything to
keep it in there.
Unfortunately, there are currently 272 xml files containing a <codenote> that
are not DTD-compliant, most of them old GWNs.
If you feel like fixing all the files that are not DTD-compliant, be me guest.
I'll give you the list of files.

For those interested:
htdocs $ for x in `find . -iname '*xml' -exec grep -l codenote {} \;`;do
xmllint --noout --valid $x 2>&1;done|grep '^\./'|cut -d: -f1|sort|uniq|wc -l
272


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\
Attachments: signature.asc (0.25 KB)


jan.kundrat at fzu

Apr 4, 2005, 12:30 PM

Post #4 of 7 (349 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

Xavier Neys wrote:
> Unfortunately, there are currently 272 xml files containing a <codenote>
> that are not DTD-compliant, most of them old GWNs.
> If you feel like fixing all the files that are not DTD-compliant, be me
> guest. I'll give you the list of files.

OK, that won't be necessary ;-). Thanks anyway.

-jkt

--
cd /local/pub && more beer > /dev/mouth
--
gentoo-doc [at] gentoo mailing list


alin at gentoo

Apr 6, 2005, 2:49 AM

Post #5 of 7 (346 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello,

Xavier Neys wrote:
>
> I can also fix all *valid* files under /doc, translations included
> (unless you want me to leave them alone and let you do it):

I've noticed that you have already fixed the files under doc/en for
<codenote>. If you are doing this to the translations, as well, please
announce when done, for the translators to `cvs update' their modified docs.

- --
Alin DOBRE
Romanian Lead Translator
Gentoo Documentation Project: http://www.gentoo.org/doc/en/
Gentoo.RO Community: http://www.gentoo.ro/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFCU7CumG51ym6Hu9gRAnsMAJ9oQosl+gpG65xdA7u5prPEysOxbQCfYZBb
VH85+pmDJo7ebLhVIehc5ro=
=fQwF
-----END PGP SIGNATURE-----
--
gentoo-doc [at] gentoo mailing list


neysx at gentoo

Apr 6, 2005, 2:53 AM

Post #6 of 7 (348 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

Alin Dobre wrote:
> Hello,
>
> Xavier Neys wrote:
>
>>>I can also fix all *valid* files under /doc, translations included
>>>(unless you want me to leave them alone and let you do it):
>
> I've noticed that you have already fixed the files under doc/en for
> <codenote>. If you are doing this to the translations, as well, please
> announce when done, for the translators to `cvs update' their modified docs.

Just done.
Anyways, you should *always* do a cvs update *before* you edit some files :)


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\
Attachments: signature.asc (0.25 KB)


martin at skjoldebrand

Apr 6, 2005, 4:47 AM

Post #7 of 7 (350 views)
Permalink
Re: Getting rid of <codenote> [In reply to]

Quoting Xavier Neys <neysx [at] gentoo>:

> Alin Dobre wrote:
>> Hello,
>>
>> Xavier Neys wrote:
>>
>>>> I can also fix all *valid* files under /doc, translations included
>>>> (unless you want me to leave them alone and let you do it):
>>
>> I've noticed that you have already fixed the files under doc/en for
>> <codenote>. If you are doing this to the translations, as well, please
>> announce when done, for the translators to `cvs update' their modified docs.
>
> Just done.
> Anyways, you should *always* do a cvs update *before* you edit some files :)

Yes, always. Good idea.
I get it... ;-)

Cheers,

Martin S.
* who going to cvs update first thing he get's home from work *



--
gentoo-doc [at] gentoo mailing list

Gentoo doc RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.