[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: another doc that should be integrated in ddp: libpkg-guide

On Sat, Dec 07, 2002 at 11:28:17AM -0600, Adam DiCarlo wrote:
> Osamu Aoki <osamu@debian.org> writes:
> > Right things to do it to convert developers-reference to docbook and
> > integrate your document.  This was too much for me.
> Yes, please don't do any such thing with the permission of the
> mainter, that is, me.  

Please think this as feasibility study for integration.  I will not
commit without your permission.  I promise :)

I put patch there so you can apply and edit it before commiting.

> Moreover, think about it -- conversion of
> debiandoc to docbook can be done mechanically.  I think it would
> probably be pretty easy to do an stylesheet to convert from DebianDoc
> to Docbook.

There was some script presented but it required some manual work.

I recall:

I tried for my "Debian reference" once but stopped it since it was a lot
of work.

> But the whole "DDP better supporting DocBook" is an entire other
> conversation, not one I want to enter just at this moment.

I understand.

> > I actually made a patch for developers-reference already.  (I
> > substituted table into list and taglist.  I know it is not as elegant
> > but missing this in developer reference is not good either.).
> Well, thanks for all that hard work, but are you sure it's really the
> right approach?  

Just think as a possible option and feasibility demonstration.
Real hard work is to rewrite content to match the style of other section.

One idea is to move this to a appendix and bump 

  sect2 -> sect
  sect3 -> sect2

That way, style difference may have been more tolerable.

> Looking at the manual you came up with (and I could have done no
> better) it seems to me that the library packaging section really
> departs from the tone of the developers reference and I think it
> should stay as a separate document.

I did not rewrite its content.  Format conversion with minimal task was
my scope of work this time.  

This writing style issue is the biggest problem.  That was beyond my
skill and requires very elaborate work.

> I don't know -- I'm undecided.  One the one hand maybe we should keep
> the document separate.  On the other hand, why bother.  Isn't it
> harder to users to jump between many documents?  Isn't it better to
> have one well-organized document?

The best scenario is one central document with consistent style, I think.

> At any rate, whether included into developers-reference or not, the
> document should at least be kept in a separate file (dealing with
> these huge SGML files gets rather ponderous).

I thought the same.  I usually split into chapter-by-chapter.

After all I am not the maintainer and it was a feasibility
demonstration, I did not bother to split the file.

~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
        Osamu Aoki <osamu@debian.org>   Cupertino CA USA, GPG-key: A8061F32
 .''`.  Debian Reference: post-installation user's guide for non-developers
 : :' : http://qref.sf.net and http://people.debian.org/~osamu
 `. `'  "Our Priorities are Our Users and Free Software" --- Social Contract

Reply to: