Documentation
¶
Overview ¶
Package html converts HTML documents (.html, .xhtml, and web pages saved as MHTML) into BDF documents in reader mode.
Like a browser's reader view, the converter keeps the content and leaves the page's design out: the article is picked out of the page (with go-readability, a port of Mozilla's Readability) and its elements take the formatting of a fixed style sheet, not the page's CSS. Headings, paragraphs, lists, quotations, code, tables, figures, links and images are laid out by the layout engine of the Word converter (converter/internal/wordproc), with the fonts embedded as subsets. BDF does not lay text out again, so the document converts into a scroll view of a fixed width (docs/spec.md §4.1); a view of A4 pages can be added.
Images are read from the files beside the document, from an MHTML archive, from data: URLs and, unless Options.NoRemote is set, from the network. See docs/design.md §3.16.
Index ¶
Constants ¶
const ( ViewsScroll = wordproc.ViewsScroll ViewsPages = wordproc.ViewsPages ViewsBoth = wordproc.ViewsBoth )
View selections.
const ( // ExtractAuto picks the article out of pages that look like they have // one (Readability's isProbablyReaderable), and keeps the whole of // other documents. ExtractAuto = "auto" // ExtractArticle always picks the article out. ExtractArticle = "article" // ExtractNone keeps the whole document. ExtractNone = "none" )
Article extraction.
Variables ¶
var Params = []conv.Param{
{Name: "views", Usage: "scroll (default): one long column; pages: A4 pages; both"},
{Name: "width", Usage: "text width of the scroll view in points (default: 36 ems of the text)"},
{Name: "size", Usage: "text size in points (default 12)"},
{Name: "font", Usage: "font family of the text (default: an installed sans-serif family)"},
{Name: "mono", Usage: "font family of code (default: an installed monospaced family)"},
{Name: "remote", Usage: "true (default): fetch images from the network; false: leave them out"},
{Name: "private", Usage: "true: fetch images from private and local addresses too (default false: public addresses only)"},
{Name: "base", Usage: "URL the document came from: relative links and images resolve against it"},
}
Params are the format-specific options of HTML and Markdown documents.
Functions ¶
func IsHTML ¶
IsHTML reports whether data starts like a whole HTML document: a doctype or an html element, after white space, comments and an XML declaration. Fragments (a README that starts with <p align="center">) are left to the Markdown converter, whose raw HTML they are.
Types ¶
type Options ¶
type Options struct {
// Views selects the views to make: ViewsScroll (the default when ""),
// ViewsPages (A4 pages) or ViewsBoth.
Views string
// Pages selects 1-based pages of the page view (see converter.Pages);
// nil keeps every page.
Pages conv.Pages
// Title overrides the document title.
Title string
// Extract controls how the article is picked out of the page:
// ExtractAuto (the default when ""), ExtractArticle or ExtractNone.
Extract string
// Dir is the directory relative references (images) resolve in;
// references and symlinks must stay within it. ""
// reads no local files. ConvertFile sets it to the file's directory.
Dir string
// BaseURL is the address of the document: relative references resolve
// against it, and links become absolute. A <base> element or the
// address an MHTML archive was saved from takes precedence.
BaseURL string
// NoRemote leaves out the images on the network instead of fetching
// them. A server that converts documents it does not trust should set
// it, or give a Fetch that limits what can be reached.
NoRemote bool
// Fetch loads an http: or https: URL; nil uses an HTTP client with a
// timeout and a size limit. It is called for several images at the same
// time.
Fetch func(url string) ([]byte, error)
// AllowPrivate lets the HTTP client fetch from addresses that are not
// public on the Internet (the host itself, its network, its link),
// which it refuses otherwise: a document a server converts could reach
// what is private to the server through them. It does not apply to
// Fetch, nor when the environment names a proxy.
AllowPrivate bool
// Width is the text width of the scroll view in points (0: 36 ems).
Width float64
// FontSize is the size of the text in points (0: 12).
FontSize float64
// Font and MonoFont are the font families of the text and of code
// ("": installed ones are picked).
Font, MonoFont string
// Images controls whether raster images are re-encoded (see imgconv).
// The zero value keeps images as they are.
Images imgconv.Options
// FontFS holds fonts that are not in the local file system; it is
// searched before FontDirs (see converter.Options.FontFS).
FontFS fs.FS
// FontDirs are searched for fonts before the system font directories.
FontDirs []string
// NoSystemFonts restricts font lookup to FontFS and FontDirs.
NoSystemFonts bool
// EmbedFonts embeds the fonts the text is laid out with, as subsets.
// By default the fonts are referred to by name (the text families as
// the generic sans-serif and monospace), and viewers draw the text with
// their own fonts, keeping the advances measured here.
EmbedFonts bool
// NoSubset embeds whole fonts instead of the glyphs in use.
NoSubset bool
// NoWOFF2 stores embedded fonts as TrueType/OpenType instead of WOFF2.
NoWOFF2 bool
// IgnoreFSType embeds fonts whose OS/2 fsType forbids embedding or
// subsetting. Set it only when you hold the rights to embed the fonts.
IgnoreFSType bool
// NoTextIndex skips building the text index parts.
NoTextIndex bool
// Warn receives non-fatal problems; when nil they are collected in
// Result.Warnings.
Warn func(msg string)
}
Options controls the conversion.
type Result ¶
type Result struct {
Doc *bdf.Document
Warnings []string
Pages int // pages of the page view
Strips int // strips of the scroll view
EmbeddedFonts int //
Extracted bool // the article was picked out of the page
Images int // images drawn
}
Result is the outcome of a conversion.
func ConvertBytes ¶
ConvertBytes converts an HTML document or an MHTML archive.
func ConvertFile ¶
ConvertFile converts an HTML or MHTML file; relative references resolve in its directory (unless opts.Dir says otherwise).