From 4db2cba5cd5025cd8c384063431e06a47f557f52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= <maelle.salmon@yahoo.se>
Date: Tue, 10 Dec 2024 07:35:36 +0100
Subject: [PATCH] docs: document argument for NCOL format in `read_graph()`

---
 R/foreign.R       | 30 +++++++++++++++++++++++++++---
 man/read_graph.Rd | 31 +++++++++++++++++++++++++++++--
 2 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/R/foreign.R b/R/foreign.R
index 6c96a1a920..573848fa09 100644
--- a/R/foreign.R
+++ b/R/foreign.R
@@ -132,7 +132,8 @@ write.graph.fromraw <- function(buffer, file) {
 #'   insensitive.
 #' @param \dots Additional arguments, see below.
 #' @return A graph object.
-#' @section Edge list format: This format is a simple text file with numeric
+#' @section Edge list format:
+#' This format is a simple text file with numeric
 #' vertex IDs defining the edges. There is no need to have newline characters
 #' between the edges, a simple space will also do. Vertex IDs contained in
 #' the file are assumed to start at zero.
@@ -142,10 +143,33 @@ write.graph.fromraw <- function(buffer, file) {
 #' then it is ignored; so it is safe to set it to zero (the default).}
 #' \item{directed}{Logical scalar, whether to create a directed graph. The
 #' default value is `TRUE`.} }
-#' @section Pajek format: Currently igraph only supports Pajek network
+#' @section Pajek format:
+#' Currently igraph only supports Pajek network
 #' files, with a `.net` extension, but not Pajek project files with
 #' a `.paj` extension. Only network data is supported; permutations,
 #' hierarchies, clusters and vectors are not.
+#' @section NCOL format:
+#' Additional arguments: \describe{
+#' \item{predef}{Names of the vertices in the file.
+#' If `character(0)` (the default) is given here
+#' then vertex IDs will be assigned to vertex names in the order of
+#' their appearance in the .ncol file.
+#' If it is not `character(0)` and some unknown vertex names are found
+#' in the .ncol file then new vertex ids will be assigned to them. }
+#' \item{names}{Logical value, if `TRUE` (the default)
+#' the symbolic names of the vertices will be added to the graph
+#' as a vertex attribute called “name”. }
+#' \item{weights}{Whether to add the weights of the edges to the graph
+#' as an edge attribute called “weight”.
+#' `"yes"` adds the weights (even if they are not present in the file,
+#' in this case they are assumed to be zero).
+#' `"no"` does not add any edge attribute.
+#' `"auto"` (the default) adds the attribute if and only
+#' if there is at least one explicit edge weight in the input file. }
+#' \item{directed}{Whether to create a directed graph (default: `FALSE`).
+#' As this format was originally used only for undirected graphs
+#' there is no information in the file about the directedness of the graph.}
+#' }
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
 #' @seealso [write_graph()]
 #' @keywords graphs
@@ -224,7 +248,7 @@ read_graph <- function(file, format = c(
 #' @export
 #' @keywords graphs
 #' @cdocs igraph_write_graph_dimacs_flow igraph_write_graph_dot igraph_write_graph_edgelist
-#' @cdocs igraph_write_graph_gml igraph_write_graph_graphml igraph_write_graph_leda 
+#' @cdocs igraph_write_graph_gml igraph_write_graph_graphml igraph_write_graph_leda
 #' @cdocs igraph_write_graph_lgl igraph_write_graph_ncol igraph_write_graph_pajek
 #' @examples
 #'
diff --git a/man/read_graph.Rd b/man/read_graph.Rd
index 6c553b3a7f..eec410f9ff 100644
--- a/man/read_graph.Rd
+++ b/man/read_graph.Rd
@@ -44,7 +44,8 @@ the file format (the \code{format} argument). See the details separately for
 each file format, below.
 }
 \section{Edge list format}{
- This format is a simple text file with numeric
+
+This format is a simple text file with numeric
 vertex IDs defining the edges. There is no need to have newline characters
 between the edges, a simple space will also do. Vertex IDs contained in
 the file are assumed to start at zero.
@@ -57,12 +58,38 @@ default value is \code{TRUE}.} }
 }
 
 \section{Pajek format}{
- Currently igraph only supports Pajek network
+
+Currently igraph only supports Pajek network
 files, with a \code{.net} extension, but not Pajek project files with
 a \code{.paj} extension. Only network data is supported; permutations,
 hierarchies, clusters and vectors are not.
 }
 
+\section{NCOL format}{
+
+Additional arguments: \describe{
+\item{predef}{Names of the vertices in the file.
+If \code{character(0)} (the default) is given here
+then vertex IDs will be assigned to vertex names in the order of
+their appearance in the .ncol file.
+If it is not \code{character(0)} and some unknown vertex names are found
+in the .ncol file then new vertex ids will be assigned to them. }
+\item{names}{Logical value, if \code{TRUE} (the default)
+the symbolic names of the vertices will be added to the graph
+as a vertex attribute called “name”. }
+\item{weights}{Whether to add the weights of the edges to the graph
+as an edge attribute called “weight”.
+\code{"yes"} adds the weights (even if they are not present in the file,
+in this case they are assumed to be zero).
+\code{"no"} does not add any edge attribute.
+\code{"auto"} (the default) adds the attribute if and only
+if there is at least one explicit edge weight in the input file. }
+\item{directed}{Whether to create a directed graph (default: \code{FALSE}).
+As this format was originally used only for undirected graphs
+there is no information in the file about the directedness of the graph.}
+}
+}
+
 \seealso{
 \code{\link[=write_graph]{write_graph()}}