Opened 6 years ago

Closed 5 years ago

#3520 closed enhancement (fixed)

add make target for PDF generation and fix formatting in PDF for kea-messages.pdf

Reported by: jreed Owned by: jreed
Priority: medium Milestone: Kea0.9.1beta
Component: documentation Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: Core Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

The docbook XML is like:

<varlistentry id="ASIODNS_SYNC_UDP_CLOSE_FAIL">
<term>ASIODNS_SYNC_UDP_CLOSE_FAIL failed to close a DNS/UDP socket: %1</term>
<listitem><para>
This is the same to ASIODNS_UDP_CLOSE_FAIL but happens on the
"synchronous UDP server", mainly used for the authoritative DNS server
daemon.
</para></listitem>
</varlistentry>

The html generation puts the explanation on new line as expected but the PDF (via dblatex) puts it on same line as the term and in some cases the explanation goes out beyond the right margin (details are lost).

This format works in other variablelist that I use in other documents, but one difference is that the variablelist is wrapped in para. Maybe is a bug in dblatex and I will research it.

Subtickets

Change History (10)

comment:1 Changed 6 years ago by jreed

  • Summary changed from fix formatting in PDF for kea-messages.pdf to add make target for PDF generation and fix formatting in PDF for kea-messages.pdf

I see this is a dblatex tunable (that I already used on previous work which is why I saw it worked for me elsewhere).

http://dblatex.sourceforge.net/doc/manual/term.breakline.html

This fixes it:
"dblatex --param=term.breakline=1"
....

I forgot this is not in doc/guide/Makefile.am so need to add target(s) to makefile too. I updated this ticket title for this.

Last edited 6 years ago by jreed (previous) (diff)

comment:2 Changed 6 years ago by tomek

  • Milestone changed from Kea-proposed to Kea0.9
  • Version set to git

comment:3 Changed 6 years ago by tomek

If time permits, would it be possible to add ISC logo on the first page of the PDF? I saw such a logo in bind9 ARM and it looked very nice.

comment:4 Changed 6 years ago by tomek

  • Milestone changed from Kea0.9 to Kea0.9.1
  • Priority changed from low to medium

comment:5 Changed 5 years ago by tomek

  • Type changed from defect to enhancement

comment:6 Changed 5 years ago by jreed

  • Owner set to jreed
  • Status changed from new to accepted

comment:7 Changed 5 years ago by jreed

  • Owner changed from jreed to UnAssigned
  • Status changed from accepted to reviewing

See trac3520 branch.
Ready for review.

comment:8 Changed 5 years ago by tomek

  • Owner changed from UnAssigned to tomek

comment:9 Changed 5 years ago by tomek

  • Owner changed from tomek to jreed

I reviewed changes on trac3520. They look good and I was able to generate PDFs for User's guide and for messages.

I have 2 comments.

kea-messages.pdf
The formatting looks good, but for longer messages the text overflows beyond right page boundary. For example on page 30 there's DHCP_DDNS_NO_ELIGIBLE_JOBS message and its description is truncated (perhaps some PDF viewers could show the text, but evince, a standard tool in Ubuntu, doesn't).

kea-guide.pdf
It would be great if the title page could include ISC logo, similar to this version of BIND9 ARM: http://ftp.isc.org/isc/bind9/cur/9.8/doc/arm/Bv9ARM.pdf.

Title page should also mention Kea version. Note that version is updated automatically (there's &__VERSION__; macro).


The code failed to build (compilation error in src/lib/dhcpsrv), but that is unrelated to this change.

As the changes are sufficiently small, I don't need to see this ticket again (unless you disagree with my suggestion).

Thank you for helping with this.

comment:10 Changed 5 years ago by jreed

  • Resolution set to fixed
  • Status changed from reviewing to closed

I merged the branch as-is to master in commit fd5a0e858140920932edbbfe215b942d2175604a.

For other items noted, I created tickets #3702 and #3703;

Note: See TracTickets for help on using tickets.