README
¶
Seed
Seed is the markup language for Bird protocol, inspired heavily by Markdown. It can also be used outside of that context as it is very simple. It is line-based and is easy to write/read in both plaintext and in a rendered format. Embedding is not supported, only linking.
Line types
Text
"$TEXT"
Normal text. A group of one or more text lines forms a paragraph unless they are within a code block. Paragraphs are separated using blank text lines. Any line that doesn't match another line type is a text line.
Header
"#{1,6} $TEXT"
A header. The header level can be one up to six with one being the highest level.
Link
"=> $TEXT ||| $URL"
A link. This links content from another URL. The text is used to give context to the link. Sometimes the URL won't be rendered at all.
Quote marker
">>>"
A quote marker. This marks both the start and end of a quote block. Only text lines are valid in a quote block.
>>>
Ninety percent of everything is crap.
~ Sturgeon's Law
>>>
Code marker
"```"
A code marker. This marks both the start and end of a code block. Only text lines are valid in a code block. Text lines do not form into paragraphs in a code block.
```
package main
import "fmt"
func main() {
fmt.Println("Hello, world!")
}
```
Other
- The MIME type is
text/seed. - UTF-8 must be used.
- Each line must end in a newline
\n, not CRLF. - Styling of the document is completely up to the client.
Best practices
- Write one sentence per text line.
- Always close your quote and code blocks.
- Do not try to control formatting using ASCII or anything.
- Use protocol-relative URLs to link to other Seed documents in the birdspace.
Example
# GNU/Linux
I'd just like to interject for a moment.
What you're referring to as Linux, is in fact, GNU/Linux, or as I've recently taken to calling it, GNU plus Linux.
Linux is not an operating system unto itself, but rather another free component of a fully functioning GNU system made useful by the GNU corelibs, shell utilities and vital system components comprising a full OS as defined by POSIX.
>>>
No, Richard, it's 'Linux', not 'GNU/Linux'.
~ Linus Torvalds.
>>>
=> GNU/Linux copypasta ||| https://wiki.installgentoo.com/wiki/Interjection
Documentation
¶
Overview ¶
Package seed reads and writes Seed documents.
Index ¶
- Constants
- Variables
- func Copy(sw *Writer, sr *Reader) (err error)
- type Code
- type Header
- type Line
- type Link
- type Quote
- type Reader
- type Text
- type Writer
- func (sw *Writer) Code() (err error)
- func (sw *Writer) Header(level int, txt string) (err error)
- func (sw *Writer) InBlock() bool
- func (sw *Writer) Line(line Line) (err error)
- func (sw *Writer) Link(txt, url string) (err error)
- func (sw *Writer) Quote() (err error)
- func (sw *Writer) Text(txt string) (err error)
Constants ¶
const (
// Extension is the standard filename extension for Seed documents.
Extension = ".sd"
)
Variables ¶
var ( // ErrBadLine indicates that it is illegal to insert the line. This usually // happens when putting a non-text line in a quote or code block. ErrBadLine = errors.New("line type cannot be added here") // ErrInvalidHeaderLvl indicates that the header level is invalid. A header // level must be between 1 and 6. ErrInvalidHeaderLvl = errors.New("invalid header level given") // ErrInvalidLine indicates that the given line type couldn't be converted // to a valid line type. ErrInvalidLine = errors.New("invalid line type given") )
Functions ¶
Types ¶
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader reads a Seed document.
sr := seed.NewReader(...)
for {
line, err := sr.ReadLine()
if err == io.EOF {
break
} else if err != nil {
return err
}
switch l := line.(type) {
case seed.Header:
fmt.Printf("header: level=%d text=%q\n", l.Level, l.Text)
case seed.Text:
fmt.Printf("text: text=%s\n", string(l))
default:
fmt.Println("other line type")
}
}
As can be seen above, the Reader reads a single line at a time. Type switches or type assertions can be to gather info on the line.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer writes documents in the Seed format.
Doc:
# Lorem ipsum >>> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. >>> => Lorem ipsum ||| https://en.wikipedia.org/wiki/Lorem_ipsum
Code:
sw := seed.NewWriter(...)
sw.Header(1, "Lorem ipsum")
sw.Break()
sw.Quote()
sw.Text("Lorem ipsum dolor sit amet,")
sw.Text("consectetur adipiscing elit,")
sw.Text("sed do eiusmod tempor incididunt")
sw.Text("ut labore et dolore magna aliqua.")
sw.Quote()
sw.Break()
sw.Link("Lorem ipsum", "https://en.wikipedia.org/wiki/Lorem_ipsum")
As can be seen above, the Writer writes a single line every time one of it's line methods is called.
func (*Writer) Code ¶
Code writes a code marker line to w. All following text lines are part of the code block. The code marker indicates the start and end of a code block. It is invalid to put anything other than text lines in a code block and all other line methods will return ErrBadLine in this case.
func (*Writer) Line ¶
Line adds a line to w. The type of this line is determined by the given line. If line is a not a valid line type, err is ErrBadLine.
func (*Writer) Quote ¶
Quote writes a quote marker line to w. All following text lines are part of the quote. The quote marker indicates the start and end of a quote block. It is invalid to put anything other than text lines in a quote block and all other line methods will return ErrBadLine in this case.
Source Files