Hey Samuel,
So I have been working on some updates to the Hurd manual. Some changes
are probably ready (once I figure out how to commit them. I can't get
magit to work on the Hurd at the moment). However, there are some other
changes where I am trying to document various Hurd functions. Here is
an example:
#+BEGIN_SRC texinfo
@node Opening Files
@subsection Opening Files
FIXME: Looking up files in directories. The comments from the code in
@file{hurd/fs.defs}, was copied in verbatium. The function definitions
may be incorrect, because I have never used these functions before.
@deftypefun error_t dir_lookup (@w{file_t @var{file}}, @w{string_t
@var{file_name}}, @w{int @var{flags}}, @w{mode_t @var{mode}}, @w{retry_type
@var{do_retry}}, @w{string_t @var{retry_name}}, mach_port_send_t @var{result})
Translate a file name, following all symlinks. Upon return, if
@var{DO_RETRY} is @var{FS_RETRY_MAGICAL} then @var{RETRY_NAME}
specifies what to do, the list of possibilities is documented in
@code{<hurd/hurd_types.h>}; if FS_RETRY_REAUTH, then @var{RESULT}
should be reauthenticated before being used. If @var{RETRY_NAME} is
the empty string and the retry type is FS_RETRY_NORMAL, then no
further @code{dir_lookup} calls are required; @var{RESULT} is the port
to use. Otherwise the @code{dir_lookup} call should be repeated, sent
to @var{RESULT} (or the reauthenticated port) with @var{RETRY_NAME}
passed for @var{FILE_NAME}. This call is required to be supported by
all files (even non-directories) if the filename is null, and should
function in that case as a re-open of the file.
@end deftypefun
@deftypefun error_t dir_readdir (@w{data_t @var{data}}, @w{int @var{entry}},
@w{int @var{nentries}}, @w{vm_size_t @var{bufsiz}}, @w{int @var{out}})
Read entries from the directory. Each entry is identified by an index
number starting at 0 and running through the file. This call fetches
@var{NENTRIES} (or any convenient number if @code{NENTRIES} is -1)
entries starting at @var{ENTRY}, returning a series of @code{struct
dirent} in @var{DATA}. Note that due to the variable-size
@var{D_NAME} field, @code{D_RECLEN} has to be used to jump from one
@code{struct dirent} to the other. The number of entries successfully
read is returned in @var{AMOUNT}. If @var{ENTRY} is bigger than the
index of the last entry, then 0 is returned in @var{AMOUNT}. If
@var{BUFSIZE} is nonzero, never return more than @var{BUFSIZE} bytes
of data regardless.
@end deftypefun
#+END_SRC
When I eventually submit this, it will probably take a fair amount of
reviewing, because I know I am probably submitting incorrect function
documentation. Any advice for how I can double check that I have
correctly documented each function?
Thanks,
Joshua
P.S. Any suggestion for how I can get magit to work on Debian/GNU Hurd
again would be a great help too. I tried using Emacs' tramp (from my
linux box), to ssh into the hurd.texi, so that I could use Linux's
Emacs' tramp-mode. That failed to work too. :(
--
Joshua Branson
Sent from the Hurd
