% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/docx_embed_font.R
\name{docx_embed_font}
\alias{docx_embed_font}
\title{Embed Fonts in a Word Document}
\usage{
docx_embed_font(
  x,
  font_family,
  regular = NULL,
  bold = NULL,
  italic = NULL,
  bold_italic = NULL
)
}
\arguments{
\item{x}{an rdocx object}

\item{font_family}{font family name as it will appear in the document.
When \code{regular} is not provided, this name is used to look up font
files via \code{\link[gdtools:sys_fonts]{gdtools::sys_fonts()}}.}

\item{regular}{path to the regular .ttf/.otf font file. If \code{NULL},
font files are detected automatically via gdtools.}

\item{bold}{path to the bold .ttf/.otf font file (optional)}

\item{italic}{path to the italic .ttf/.otf font file (optional)}

\item{bold_italic}{path to the bold-italic .ttf/.otf font file (optional)}
}
\value{
the rdocx object with embedded fonts
}
\description{
Copy TrueType or OpenType font files from the local
system into a Word document. The font data is stored inside the
\code{.docx} archive so that the document renders correctly when opened
on a system where the font is not installed.

When only \code{font_family} is provided (without \code{regular}), the function
looks up font file paths on the local system via \code{\link[gdtools:sys_fonts]{gdtools::sys_fonts()}}
and copies them into the document. A message shows the equivalent
explicit call for reproducibility.
}
\section{Font licensing}{

Embedding a font in a document redistributes it. You must ensure that
the font license permits embedding. Fonts under the SIL Open Font
License (e.g. Liberation, Google Fonts) generally allow it. Many
commercial fonts restrict or prohibit embedding. Check the license
of the font before using this function.
}

\examples{
\dontshow{if (require("gdtools", quietly = TRUE, character.only = TRUE)) withAutoprint(\{ # examplesIf}
# automatic detection (requires gdtools)
gdtools::register_liberationsans()
doc <- read_docx()
doc <- docx_embed_font(doc, font_family = "Liberation Sans")

# # explicit paths (no gdtools needed)
# doc <- docx_embed_font(
#   doc,
#   font_family = "My Font",
#   regular = "path/to/font-regular.ttf",
#   bold = "path/to/font-bold.ttf"
# )
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[gdtools:sys_fonts]{gdtools::sys_fonts()}}, \code{\link[gdtools:register_gfont]{gdtools::register_gfont()}},
\code{\link[=docx_set_settings]{docx_set_settings()}}
}
