Re: I need some help with my first steps using Debian Doc / SGML
On Sun, May 07, 2006 at 04:35:02PM -0400, andrei raevsky wrote:
> On 5/7/06, Jens Seidel <jensseidel@users.sf.net> wrote:
>
> >> 2) do I need to install debiandoc-sgml-doc and if yes, what for?
> >
> >That's really a funny question, since it's obvious to me that the
> >debiandoc-sgml-doc package contains the documentation of
> >debiandoc-sgml (/usr/share/doc/debiandoc-sgml-doc/) which you
> >requested in 1) :-))
> >Just install it beside debiandoc-sgml!
>
> this is because I am confused about what debiandoc-sgml exaclty is and
> whether debiandoc-sgml-doc contains the documentation for the package
> or the DDP or a list of legal tags... sorry if I did not make that
> clear. this is all made worse by the fact that I am not in front of
> my Debian Sarge computer so I cannot simply look up the info in
> apt-cache
That is a set of SGML conversion convienience scripts.
> >> 3) how can I best check my tags before submitting them?
> >
> >It is really a good idea to *always* test your file(s) using the tools in
> >debiandoc-sgml package:
> >debiandoc2latexpdf -l en yourFile.sgml
> >This should produce a PDF output file (you need tetex-bin and
> >tetex-extra package for this).
> >
> >Similar tools: debiandoc2text, debiandoc2html, debiandoc2latexps
> >
> >See the manual page for details (man debiandoc2html).
> >
> >Feel free to look into examples (all DDP documents).
> >You will probably need only a few tags, such as for
> > * headlines
> > * item lists
> > * references
> >
> >You should also use a few special tags such as <file> when referring to
> >file or directory names, <package> for Debian packages, <prgn> for
> >programs, ...
>
> I am still confused. Please keep in mind that most of the packages
> and tools you are referring to are totally unknown to me (what is
> tetext? what does it have to do with SGML?). is there a step-by-step
> 'tutorial for dummies' out there I could read which would tell me a)
> what I need to install b) how I get started c) what tags I can use d)
> how I check my tags and why a PDF of my file allows me to check
> anything? how do I know what to look for on a PDF? I have never used
> a PDF to check for code - only to created print-like documents...
You should read all these documented in debiandoc-sgml-doc package.
> >> 4) is there a Debian Doc editor or an editor best suited to edit
> >> Debian Doc SGML documents?
> >
> >Since the number of editors is finite there surely exists a best one in
> >this set. Which one? I don't know. I use vim, other emacs, ... it's
> >really your decision.
>
> I did not mean regular editors (I, personally, always use vi). I
> thought that maybe there was one which would allow an immediate
> preview of the SGML file just like QuantaPlus does for HTML ?
>
> Can't I simply get a list of legal tags online, use my good old vi to
> enter text and tags and then use not several, but one application to
> check my stuff? Is there an extension for Firefox or Konqueror which
> allows you to parse SGML pages and check it?
I used just vim and mcedit to make Debian Reference which is big
documentws. mcedit was used to cope with non-ascii translations.
> I would much rather use a few tools I have on all my machines then
> install tons of applications which are new to me. but if that is not
> an option - I will do it the hard way.
Easy way is not to use many tags :-)
> Thanks for your patience and please let me know what my options are.
If you are thinking of creating guide document which will evolve with
time, please loook into (semi)official site such as wiki.debian.org
I have to admit the learning curve of SGML is a bit steaper than
creating wiki pages.
Once you have web page you can always convert to XML document if you are
good at scripting.
Osamu
Reply to: