+
1. Getting Started
+
-
1.2. Section A.b
-
-
1.2.1. Section that shall not be in ToC
+1.1. Introduction
+`
+ Expect(RenderHTML(source)).To(MatchHTML(expected))
+ })
+
+ It("with numbering disabled and enabled again - case 2", func() {
+ source := `---
+draft: true
+---
+
+= User Manual
+
+:sectnums!:
+
+== Disclaimer
+
+== Acknowledgments
+
+:sectnums:
+
+== Getting Started
+
+=== Introduction`
+
+ expected := `
-
2. Section B
+
Acknowledgments
-
3. Section C
+
1. Getting Started
`
Expect(RenderHTML(source)).To(MatchHTML(expected))
})
+
})
Context("with elements", func() {
diff --git a/pkg/renderer/sgml/renderer.go b/pkg/renderer/sgml/renderer.go
index 6a40cdd3..120a9de0 100644
--- a/pkg/renderer/sgml/renderer.go
+++ b/pkg/renderer/sgml/renderer.go
@@ -162,7 +162,7 @@ func (r *sgmlRenderer) Render(ctx *renderer.Context, doc *types.Document, output
renderedTitle = DefaultTitle
}
// process attribute declaration in the header
- if header := doc.Header(); header != nil {
+ if header, _ := doc.Header(); header != nil {
for _, e := range header.Elements {
switch e := e.(type) {
case *types.AttributeDeclaration:
@@ -252,7 +252,8 @@ func (r *sgmlRenderer) splitAndRender(ctx *renderer.Context, doc *types.Document
func (r *sgmlRenderer) splitAndRenderForArticle(ctx *renderer.Context, doc *types.Document) (string, string, error) {
log.Debugf("rendering article (within HTML/Body: %t)", ctx.Config.WrapInHTMLBodyElement)
- renderedHeader, err := r.renderDocumentHeader(ctx, doc.Header())
+ header, _ := doc.Header()
+ renderedHeader, err := r.renderDocumentHeader(ctx, header)
if err != nil {
return "", "", err
}
@@ -270,7 +271,8 @@ func (r *sgmlRenderer) splitAndRenderForManpage(ctx *renderer.Context, doc *type
elements := doc.BodyElements()
nameSection := elements[0].(*types.Section) // TODO: enforce
if ctx.Config.WrapInHTMLBodyElement {
- renderedHeader, err := r.renderManpageHeader(ctx, doc.Header(), nameSection)
+ header, _ := doc.Header()
+ renderedHeader, err := r.renderManpageHeader(ctx, header, nameSection)
if err != nil {
return "", "", err
}
@@ -296,14 +298,14 @@ func (r *sgmlRenderer) splitAndRenderForManpage(ctx *renderer.Context, doc *type
}
func (r *sgmlRenderer) renderDocumentRoles(ctx *renderer.Context, doc *types.Document) (string, error) {
- if header := doc.Header(); header != nil {
+ if header, _ := doc.Header(); header != nil {
return r.renderElementRoles(ctx, header.Attributes)
}
return "", nil
}
func (r *sgmlRenderer) renderDocumentID(doc *types.Document) string {
- if header := doc.Header(); header != nil {
+ if header, _ := doc.Header(); header != nil {
// if header.Attributes.Has(types.AttrCustomID) {
// We only want to emit a document body ID if one was explicitly set
return r.renderElementID(header.Attributes)
@@ -313,7 +315,7 @@ func (r *sgmlRenderer) renderDocumentID(doc *types.Document) string {
}
func (r *sgmlRenderer) renderAuthors(_ *renderer.Context, doc *types.Document) string { // TODO: pass header instead of doc
- if header := doc.Header(); header != nil {
+ if header, _ := doc.Header(); header != nil {
if a := header.Authors(); a != nil {
authorStrs := make([]string, len(a))
for i, author := range a {
@@ -330,7 +332,7 @@ func (r *sgmlRenderer) renderAuthors(_ *renderer.Context, doc *types.Document) s
const DefaultTitle = "Untitled"
func (r *sgmlRenderer) renderDocumentTitle(ctx *renderer.Context, doc *types.Document) (string, bool, error) {
- if header := doc.Header(); header != nil {
+ if header, _ := doc.Header(); header != nil {
// TODO: This feels wrong. The title should not need markup.
title, err := r.renderPlainText(ctx, header.Title)
if err != nil {
diff --git a/pkg/types/section_numbering_test.go b/pkg/types/section_numbering_test.go
index a913aca7..43c35f82 100644
--- a/pkg/types/section_numbering_test.go
+++ b/pkg/types/section_numbering_test.go
@@ -22,18 +22,18 @@ var _ = Describe("section numbering", func() {
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1",
+ types.AttrID: "_getting_started",
},
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1a",
+ types.AttrID: "_introduction",
},
Elements: []interface{}{},
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1b",
+ types.AttrID: "_download_and_install",
},
Elements: []interface{}{},
},
@@ -46,9 +46,9 @@ var _ = Describe("section numbering", func() {
// then
Expect(err).NotTo(HaveOccurred())
- Expect(n["_section_1"]).To(Equal("1"))
- Expect(n["_section_1a"]).To(Equal("1.1"))
- Expect(n["_section_1b"]).To(Equal("1.2"))
+ Expect(n["_getting_started"]).To(Equal("1"))
+ Expect(n["_introduction"]).To(Equal("1.1"))
+ Expect(n["_download_and_install"]).To(Equal("1.2"))
})
It("should always number sections - explicitly in document body", func() {
@@ -60,18 +60,18 @@ var _ = Describe("section numbering", func() {
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1",
+ types.AttrID: "_getting_started",
},
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1a",
+ types.AttrID: "_introduction",
},
Elements: []interface{}{},
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1b",
+ types.AttrID: "_download_and_install",
},
Elements: []interface{}{},
},
@@ -84,9 +84,9 @@ var _ = Describe("section numbering", func() {
// then
Expect(err).NotTo(HaveOccurred())
- Expect(n["_section_1"]).To(Equal("1"))
- Expect(n["_section_1a"]).To(Equal("1.1"))
- Expect(n["_section_1b"]).To(Equal("1.2"))
+ Expect(n["_getting_started"]).To(Equal("1"))
+ Expect(n["_introduction"]).To(Equal("1.1"))
+ Expect(n["_download_and_install"]).To(Equal("1.2"))
})
It("should never number sections - explicitly", func() {
@@ -98,18 +98,18 @@ var _ = Describe("section numbering", func() {
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1",
+ types.AttrID: "_getting_started",
},
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1a",
+ types.AttrID: "_introduction",
},
Elements: []interface{}{},
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1b",
+ types.AttrID: "_download_and_install",
},
Elements: []interface{}{},
},
@@ -131,18 +131,18 @@ var _ = Describe("section numbering", func() {
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1",
+ types.AttrID: "_getting_started",
},
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1a",
+ types.AttrID: "_introduction",
},
Elements: []interface{}{},
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1b",
+ types.AttrID: "_download_and_install",
},
Elements: []interface{}{},
},
@@ -175,18 +175,18 @@ var _ = Describe("section numbering", func() {
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1",
+ types.AttrID: "_getting_started",
},
Elements: []interface{}{
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1a",
+ types.AttrID: "_introduction",
},
Elements: []interface{}{},
},
&types.Section{
Attributes: types.Attributes{
- types.AttrID: "_section_1b",
+ types.AttrID: "_download_and_install",
},
Elements: []interface{}{},
},
@@ -200,8 +200,63 @@ var _ = Describe("section numbering", func() {
// then
Expect(err).NotTo(HaveOccurred())
Expect(n["_disclaimer"]).To(BeEmpty())
- Expect(n["_section_1"]).To(Equal("1"))
- Expect(n["_section_1a"]).To(Equal("1.1"))
- Expect(n["_section_1b"]).To(Equal("1.2"))
+ Expect(n["_getting_started"]).To(Equal("1"))
+ Expect(n["_introduction"]).To(Equal("1.1"))
+ Expect(n["_download_and_install"]).To(Equal("1.2"))
+ })
+
+ It("should number sections when enabled - case 2", func() {
+ // given
+ doc := &types.Document{
+ Elements: []interface{}{
+ &types.FrontMatter{
+ Attributes: map[string]interface{}{
+ "draft": true,
+ },
+ },
+ &types.DocumentHeader{
+ Title: []interface{}{},
+ },
+ &types.AttributeReset{
+ Name: types.AttrSectionNumbering,
+ },
+ &types.Section{
+ Attributes: types.Attributes{
+ types.AttrID: "_disclaimer",
+ },
+ },
+ &types.AttributeDeclaration{
+ Name: types.AttrSectionNumbering,
+ },
+ &types.Section{
+ Attributes: types.Attributes{
+ types.AttrID: "_getting_started",
+ },
+ Elements: []interface{}{
+ &types.Section{
+ Attributes: types.Attributes{
+ types.AttrID: "_introduction",
+ },
+ Elements: []interface{}{},
+ },
+ &types.Section{
+ Attributes: types.Attributes{
+ types.AttrID: "_download_and_install",
+ },
+ Elements: []interface{}{},
+ },
+ },
+ },
+ },
+ }
+ // when
+ n, err := doc.SectionNumbers()
+
+ // then
+ Expect(err).NotTo(HaveOccurred())
+ Expect(n["_disclaimer"]).To(BeEmpty())
+ Expect(n["_getting_started"]).To(Equal("1"))
+ Expect(n["_introduction"]).To(Equal("1.1"))
+ Expect(n["_download_and_install"]).To(Equal("1.2"))
})
})
diff --git a/pkg/types/types.go b/pkg/types/types.go
index 4913191a..ecd2444c 100644
--- a/pkg/types/types.go
+++ b/pkg/types/types.go
@@ -101,21 +101,33 @@ type Document struct {
TableOfContents *TableOfContents
}
+// FrontMatter returns the FrontMatter element if it is in the first position
+// in the document, `nil` otherwise.
+func (d *Document) FrontMatter() *FrontMatter {
+ if frontmatter, ok := d.Elements[0].(*FrontMatter); ok {
+ return frontmatter
+ }
+ return nil
+}
+
// Header returns the header, i.e., the section with level 0 if it found as the first element of the document
// For manpage documents, this also includes the first section (`Name` along with its first paragraph)
-func (d *Document) Header() *DocumentHeader {
- if len(d.Elements) == 0 {
- log.Debug("no header for empty doc")
- return nil
- }
- // expect header (if it exists) to be in first position of the doc
- if h, ok := d.Elements[0].(*DocumentHeader); ok {
- return h
- }
- if log.IsLevelEnabled(log.DebugLevel) {
- log.Debugf("no header in document: %T", d.Elements[0])
+// also returns the position of the DocumentHeader element in the Document's Elements (in case there's a FrontMatter before, for example)
+func (d *Document) Header() (*DocumentHeader, int) {
+elements:
+ for i, e := range d.Elements {
+ switch e := e.(type) {
+ case *DocumentHeader:
+ return e, i
+ case *BlankLine, *FrontMatter:
+ // expect DocumentHeader to be positioned after optional FrontMatter and blanklines in-between
+ continue
+ default:
+ log.Debugf("no header in document")
+ break elements
+ }
}
- return nil
+ return nil, -1
}
// BodyElements returns the elements to render in the body
@@ -145,10 +157,10 @@ type SectionNumbers map[string]string // assigned number by section id
func (d *Document) SectionNumbers() (SectionNumbers, error) {
enabled := false
- if h := d.Header(); h != nil {
+ if header, _ := d.Header(); header != nil {
// lookup the `sectnums` or `numbered` attribute in the header
var err error
- if _, enabled, err = traverseElements(h.Elements, false, ""); err != nil {
+ if _, enabled, err = traverseElements(header.Elements, false, ""); err != nil {
return nil, err
}
}
diff --git a/pkg/validator/validator.go b/pkg/validator/validator.go
index a911d3ce..b7060767 100644
--- a/pkg/validator/validator.go
+++ b/pkg/validator/validator.go
@@ -42,7 +42,7 @@ const (
func validateManpage(doc *types.Document) []Problem {
problems := []Problem{}
// checks the presence of a header
- if doc.Header() == nil {
+ if header, _ := doc.Header(); header == nil {
problems = append(problems, Problem{
Severity: Error,
Message: "manpage document is missing a header",