IdeaListOld [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
Here are some TODO items for The %%FreeBSD%% Documentation Project. Some of these are smaller tasks, which are relatively easy to solve and some are more complicated, longer term tasks.

Note: Just because an idea is on this page it does not mean there is guarantee that there exists a consensus that the idea is a good one.

====== Documentation Project TODO List ======

^ Task ^ Description ^ Status ^ Responsible ^
| Convert docproj/todo.html to the [[/DocIdeaList|DocIdeaList]] | The TODO list needs to be merged over to the Wiki, and docproj/todo.html needs to be retired. | Not started | [[/GlenBarber|GlenBarber]] |

====== VCS ======

^ Task ^ Description ^ Status ^ Responsible ^
| Define a good SVN layout | To migrate the doc+www sources to Subversion, first we need to define a good layout for the new repository. | Completed | doceng, see their [[http://lists.freebsd.org/pipermail/freebsd-doc/2012-March/019628.html|announcement]] for more info |
| Convert the CVS repository to SVN | Do the actual migration. | Completed | doceng, see their [[http://lists.freebsd.org/pipermail/freebsd-doc/2012-March/019628.html|announcement]] for more info |
| Set up CVS exporter | We still need to provide the sources in CVS for CVSup servers and to feed out Perforce development repository. | Cancelled. Evaluated to be unnecessary. | doceng |

====== Documentation Infrastructure ======

^ Task ^ Description ^ Status ^ Responsible ^
| Entity cleanups | Entities may be organized much better than we do currently. Sometimes, entities logically belonging to the same category are split into various files (trademarks.sgml and trademarks.ent) and translations do not use entity sets correctly. It seems that the general concept is not widely understood and some translations just copy English entities instead of pulling them in appropriately. This should be cleanup up and simplified in order to avoid later misuses. | Completed | GáborKövesdán |
| Migrate to %%DocBook%% 4.2/XML | SGML is quite an old standard and (Open)Jade is an outdated software, whose development is discontinued. XML-ifying our documentation set would give us the opportunity to use a more modern toolset and newer standards. It has a lot of advantages, which do not fit here. This task implies upgrading the DTD to 4.2 because that is the first version, where XML is also supported. | Completed | GáborKövesdán |
| Use XSL to generate HTML output | After XML-ifying the doc tree, we should replace (Open)Jade for HTML output generation. This is quite trivial, while the RTF, PS and PDF outputs are more problematic. | In progress | GáborKövesdán |
| Evaluate xmlroff and Apache FOP for RTF, PS and PDF rendering | It would be nice if we could totally replace (Open)Jade after XML-ifying the tree and xmlroff may be a good candidate for this. However, when GáborKövesdán last checked it, its output was not mature enough. Apache FOP generates a very high quality output but it is written in Java, which may be an expensive dependency. At least optional support for these tools should be added even if they cannot replace (Open)Jade yet. | In progress | GáborKövesdán |
| XHTMLify webpages | Just like for our %%DocBook%% documentation, the SGML vs. XML question also applies to the webpages, so they should be migrated to XML to use a more modern toolset. | Completed | GáborKövesdán |
| Move webpages to the doc directory inside the top-level language directories | To facilitate information sharing between documentation and webpages, it would be practical to move the webpages next to the articles and books directories. | Completed | [[/HirokiSato|HirokiSato]] |
| Make web script multilingual | Our main Web pages are written in (American) English. The %%FreeBSD%% Translations Projects translate the web pages, Handbook and FAQ to other languages. We must translate the CGI scripts and web build scripts too. The scripts should support multiple languages, not only one. Most scripts are written in Perl. Merge the Perl scripts www/en/ports/portindex and www/ja/ports/portindex into one script. Add an option for English and Japanese output. | Not started | Not assigned |
| Enhance search engine | When searching the website, the output from the search engine includes the filename that was found, which might be something like FAQ34.html. It would be more useful if the results included the question text, allowing the user to see whether or not the result was relevant. | Done (now using %%DuckDuckGo%%) | [[/GavinAtkinson|GavinAtkinson]] |

====== Website ======

^ Task ^ Description ^ Status ^ Responsible ^
| Dynamic web app for project ideas | Murray has started a project to move the static ideas.xml file used to keep track of summer of code and other development projects seeking volunteers into a dynamic web app that allows users to vote and post comments about the items so that it is clear which projects have the most support and so that it is easier to make updates.  See the design doc in [[MurrayStokely/IdeasWebApp|MurrayStokely/IdeasWebApp]] | Unknown | [[/MurrayStokely|MurrayStokely]] |
| XMLified publications page | [[/JosefElRayes|JosefElRayes]] started with XML'ifying the Publications Pages. I will try to make it up to date like the %%UserGroups%% and perhaps implement information found on this XSLT/XML info into the %%UserGroups%%. Reference: [[http://www.freebsd.org/cgi/query-pr.cgi?pr=59307|PR www/59307]] | In progress | [[/RemkoLodder|RemkoLodder]] |
| XML/XSL-based web calendar | With some nice xml/xsl code (based on simons eventscalendar) we could create a nice calendar that covers all needed dates, like releng dates, freezes and so on. it could be reused multiple times on the website. Some XSL or Perl code could also make it create some calendar(1) or perhaps even ical compatible output. | Unknown | [[/JosefElRayes|JosefElRayes]] |
| Review http://www.freebsd.org/java/ | Review http://www.freebsd.org/java/ and suggest improvements. A lot of information over there is probably highly outdated and there may be quite a few dead links. | Completed | [[/EitanAdler]] |
| Track down and solve rendering issues | After the introduction of new layout, many persons reported a font size or rendering problems under some browsers configurations and screen resolutions. These problems should be investigated and fixed. Reference: [[http://www.freebsd.org/cgi/query-pr.cgi?pr=91539|www/91539]] | Not started | Not assigned |
| Refactor CGI scripts | Modify the CGI scripts url.cgi, ports.cgi, pds.cgi and the script portindex to use the Perl %%FreeBSD%%::Ports modules. These modules also need thorough testing. | Not started | [[/WolframSchneider|WolframSchneider]] |

====== Handbook ======

^ Task ^ Description ^ Status ^ Responsible ^
| Add a section to the network servers chapter on setting up JBoss | Tomcat is merely a Java web container so it cannot run e.g. EJB3. In such cases, an application server, like JBoss is necessary. We lack information on how to use it on %%FreeBSD%%. | Not started | Not assigned |
| Add some info on how to tune network performance | On [[/NetworkPerformanceTuning|NetworkPerformanceTuning]], there are some tunables and sysctls listed. Those should be explained in handbook. | Not started | Not assigned |
| Extend jails chapter with tips and useful utilities | The [[/Jails]] wiki page has some tips and useful utilities but the content is rather a sketch. It needs to be transformed an easy to understand fluent text. | Not started | [[/SeanCollins|SeanCollins]] |
| Add performance tweaks to correspoding chapter | There are some performance tweaks on [[/PerformanceTweaks|PerformanceTweaks]]. These should be merges to the corresponding chapter of handbook. | Not started | Not assigned |
| Harvest [[http://people.freebsd.org/~linimon/studies/prs/prs_for_tag_handbook.html|PRs about the handbook]] | The bugmeisters keep a page of suggested patches to the handbook; it is updated once a day. | Not started | Not assigned |
| Write a wine section | Some notes are available on [[/Wine]]. | Not started | Not assigned |
| Merge available information on ZFS to handbook | We have some pieces of valuable information and references on the [[/ZFS]] wiki page. These include the quick start instructions, tuning, how to use ZFS for root filesystem, how to install a ZFS-only system, etc. These are quite important notes and should be merged to handbook so that they can get more exposure. | Not started | [[/DavidRhodus|DavidRhodus]] |
| Review information on USB | Check the completeness on how to use USB devices and check if the FAQ entries on the [[/USB]] wiki page are answered in handbook. | Not started | Not assigned |
| Review information on ATA/SATA disks | Check if we can merge something from the troubleshooting part of the !ATA_issues_and_troubleshooting wiki page. (Editors's note: page deleted as of 2018.) | Not started | Not assigned |
| Write a javavmwrapper guide | The javavmwrapper tool is powerful, but probably not well-known. Describe the tool in a simple manner and make it available in an official easy to find places. This so that people know how to use the various JDKs that are installed without using aliases or modifying PATH. Same for describing where to find and how to use installed JAR files (see PR/56928). | Not started | Not assigned |
| Document JDK ports | Provide up-to-date information on the status of the Java SE 5 port, the expectations regarding the Java SE 6 port. Detail the characteristics of the ports, such as stability, security and performance compared to other platforms. | Not started | Not assigned |
| Update installation chapter | The installation chapter mostly covers %%FreeBSD%% 4.X installation. The current information is often outdated and not accurate for 5.X, 6.X and 7.X. We also have to think about installation on various platforms. This should be done under re@ team responsibility since the installation notes have to be updated as well. | Not started | [[/GiorgosKeramidas|GiorgosKeramidas]] |
| Add quick and easy setup example to printing chapter | While this chapter covers in a very accurate way the configuration of a printer under %%FreeBSD%%, a quick and easy printer setup should be documented, i.e., something describing the installation and use of apsfilter or equivalent. | Not started | Not assigned |
| Add info on USB printers | Nowadays printers use the USB interface, the printing chapter may need to be updated on this point. | Not started | Not assigned |
| Merge wireless article to handbook | The merge of [[http://www.freebsdmall.com/~loader/en_US.ISO8859-1/articles/wireless/article.html|this article]] in the current wireless section should be done quickly. | Not started | [[/MurrayStokely|MurrayStokely]], [[/MarcFonvieille|MarcFonvieille]] |
| Update IPSec section | This section still shows the use of gifconfig(4) which is 4.X only. | Not started | [[/RemkoLodder|RemkoLodder]] |
| Review USB audio section | One should check if we need to update the sound section for USB devices or if the current guidance is still correct with these devices. | Not started | Not assigned |
| Update emergency restore section | This section is really outdated and needs a serious "facelifting." We must show how to restore a system using the livefs from disc1. The rescue system should also be covered. | Not started | Not assigned |
| Write a section on basic backup | Backing up on optical media (CD/DVD) should be presented. | Not started | Not assigned |
| Update electronic mail section | The use of Makefile facilities should be introduced for the sendmail configuration instead of the old outdated way. | Not started | %%JesusRCamou%%, [[/SeanCollins|SeanCollins]] |
| Document configuring bsnmpd | The bsnmpd daemon is quite new and its configuration may be complex. The minimal common settings should be introduced in a section of the Network Servers chapter. | Not started | Not assigned |
| Add some more tips and hints on portupgrade | There are some hints and tips on the [[/portupgrade]] page, which would fit better into the corresponding part of handbook | Not started | Not assigned |
| Extract relevant information from Samba mini FAQ and add them to handbook | There are some notes on [[Samba/MiniFAQ|Samba/MiniFAQ]], which would fit better in handbook. | Not started | Not assigned |
| Improve indexing | Many new sections have been added to the %%FreeBSD%% Handbook without index terms, others have been added under inappropriate primary or secondary indexterms that do not fit the existing scheme. Some indexterms have been added inside list items or other areas where they are not allowed by our stylesheets, causing ??? to be printed in the index instead of a real page number. Index work requires experience and anyone who works on this task is highly encouraged to carefully read through the existing (print-output) index, and to have read the Chicago Manual of Style or other style books that deal with indexing. Please see the CVS history of some of the chapter.sgml files to see some of the indexing errors that have been corrected in the past. It is imperative to view the %%PostScript%% version of the Handbook after making any changes to indexterms as many errors, such as long words or deeply nested indexterms will break the two column output there, or cause the page number to be listed as ???. There is a script doc/share/misc/indexreport.pl which can be used to find areas of an SGML file where %%<%%indexterms> are sparse. | Not started | Not assigned |
| Update Firewall chapter | The chapter about firewalls in the handbook is becoming seriously outdated. We should also change the order in which the firewalls appear in this chapter. A better order would be: first IPFW, then pf and last ipfilter. The IPFW section should probably be rewritten and it should mention in-kernel NAT. | Not started | Not assigned |
| Check Configuration and Tuning chapter | The Configuration and Tuning chapter documents some settings which might not be relevant anymore (kern.maxfiles, maxusers, NMBCLUSTERS) | Not started | Not assigned |
| Update the Serial Communications chapter | Check if the device configuration is now version-independent (modulo node names), add an introduction | Not started | Not assigned |
| Update the Cutting-Edge Chapter for the Documentation Project CVS->SVN Conversion | ryusuke pointed out in private email that the cutting-edge chapter needs updating since c(v)sup is still mentioned for updating the documentation set.  Since we do not do SVN->CVS conversion on the backend, this chapter needs updating.  Normally, I would just update/commit, but since the changes will be rather large, I will wait until after the doc slush. | Somewhat Started | [[/GlenBarber|GlenBarber]] |

The following list was compiled from the doc session at the [[DevSummit/201010|EuroBSDCon 2010 Devsummit]]:

^ Task ^ Description ^ Status ^ Responsible ^
| Remove SLIP | SLIP is outdated and was removed from the kernel a while ago. Some PRs were sent with patches to remove SLIP from the handbook. | not started | not assigned |
| Remove ISDN | ISDN has been surpassed by DSL modems and is not being used that often as it was in the past. However, the ISDN mailing list was not removed, so maybe we should discuss whether we still need this section in the handbook. | not started | not assigned |
| Advanced/Domain specific topics | Some topics that are covered in articles could be moved to the handbook. However, this is not intended to replace the articles in general, just to get their content exposed to a wider audience. | not started | not assigned |
| More filesystems | There are many filesystems that are available in %%FreeBSD%% like [[/TMPFS]] and others. However, only ZFS is currently being described in the handbook. Add new sections about the other filesystems, their characteristics and usage. | not started | not assigned |
| Different Installation scenarios | Currently, only the standard installation via sysinstall is described. There are many other good instructions in the %%FreeBSD%% Wiki and Forums describing alternative installation methods (i.e. ZFS only, diskless). Add these in a separate section for advanced users. | not started | not assigned |
| Make security a top level chapter | There are many parts in the handbook that deal with security or have security related content. Security should be a top level chapter for people interested in system security. Appropriate sections need to be discussed (i.e. where to put jails: security or virtualization?) and moved there accordingly. | not started | not assigned |
| Popular chapters/sections | Analyze which chapters/sections are being accessed the most. That way, we can get a feel for what chapters need more polishing, need to be updated or removed. Something like [[http://www.google.com/intl/en/analytics/index.html|Google Analytics]] might be helpful, but other tools might be just as good. | not started | not assigned |
| EPUB format | The [[http://en.wikipedia.org/wiki/EPub|EPUB format]] is a free and open e-book standard for different electronic devices like ebook readers, tablets or mobile phones. It would be nice to have the %%FreeBSD%% handbook in this format so that users can read the handbook on these devices as well. | In progress, see also [[/PublishedFormats|PublishedFormats]] or this [[http://www.bsdcan.org/2011/schedule/events/224.en.html|BSDCan2011 presentation]] | [[/BenedictReuschling|BenedictReuschling]] |
| Print format | There is still a demand for a printed version of the handbook from customers of e.g. %%FreeBSD%% Mall. The [[http://www.freebsdmall.com/cgi-bin/fm/bsdhandbk3.1|current third edition]] covers %%FreeBSD%% 4.X and 5.X only. It was recommended to compile the current handbook into three separate books: 1) %%FreeBSD%% installation and basic system administration 2) %%FreeBSD%% as a server OS 3) %%FreeBSD%% as a desktop OS. | Started, see [[/PublishedFormats|PublishedFormats]] | not assigned |
| Mark outdated parts | Some parts of the handbook only apply to older versions of %%FreeBSD%% that are still being maintained. In order to let users know that some information applies only to specific versions, we need to mark these sections as outdated with the time of the last update/check. | not started | not assigned |

====== Porters' Handbook ======

^ Task ^ Description ^ Status ^ Responsible ^
| Add a section on Haskell ports | This task includes some general notes and the use of the hsporter utility. For the latter, there's a short description [[http://code.haskell.org/~pgj/projects/hsporter/README|here]]. | Not started | Not assigned |
| Review and separate user and developer content | Currently, porters-handbook combines some knowledge on using the Ports Collection and knowledge to develop ports. However, it is only meant to be the latter. Content that targets end-users should be moved to handbook. | Not started | Not assigned |
| Move policies to a more appropriate place | Porters-handbook is for technical details of the development, while it also contains some information on policies. The latter should be moved to the [[http://www.freebsd.org/portmgr/policies.html|portmgr policies]] part of the webpage to avoid duplication and limit porters-handbook's content more strictly to the topic. | Not started | Not assigned |
| Better emphasize requirements and recommendations | We (portmgr) have to make it clear what things are Recommendations and what things are Requirements. e.g. exactly what is portmgr willing to enforce with, if necessary, backouts and commit bit suspensions. This way everyone who chafes under any "new policy" can figure out where they stand (whether it is one or the other). | Not started | Not assigned |
| Reorder introduction and detailed descriptions | Many things are discussed in detail even before all the general concepts have been introduced. Things need to be reordered. | Not started | Not assigned |
| Document common practices | About half of the "accepted practices" are missing. | Not started | Not assigned |
| Review consistency and logical structure of sections | Some of the things in "Do's And Don'ts" appear much too late. Some of the other things aren't even appropriate for that section. | Not started | Not assigned |
| Reorganize appendices | Some of the text (list of Makevars) needs to come out of where it currently is and be in Appendices. References to the Appendices should then take their place. (Or maybe not.) | Not started | Not assigned |
| Fill up emacs section | The emacs section is incomplete. | Not started | [[/AndreySlusar|AndreySlusar]] |
| Document new *_DEPENDS style | New *_DEPENDS style with <,>,<=,>= is not described. | Not started | Not assigned |
| Document porting Mozilla's XPI extensions, NPAPI extensions and Linkfarming | There are some notes on the [[AndrewPantyukhin/NPAPI]] and [[AndrewPantyukhin/Linkfarming]] pages. | Not started | Not assigned |
| Document Portscout Variables for Port Makefiles | Port Makefiles support the use of PORTSCOUT variables to limit what Portscout will report as a new version of software.  For a quick list, run: find /usr/ports -type f -name Makefile -maxdepth 3 %%|%% xargs grep PORTSCOUT | Not started | Not assigned |

====== Developers' Handbook ======

This book needs more content. It seems a sketch rather than a consistent document. There are lots of uncovered areas but there are some sporadic pieces of information on the wiki, which could be SGML-ified and merged to the book.

^ Task ^ Description ^ Status ^ Responsible ^
| Merge description on Linux cross-development | There is a short description on how to use %%FreeBSD%% for cross-developing Linux binaries on [[/linux-xdev]]. Someone should SGML-ify and merge these to developers-handbook. | Not started | Not assigned |
| Add content on general debugging | Some information may be extracted from [[/Debugging]]. | Not started | Not assigned |
| Add content on using profiling to detect performance bottlenecks | Profiling with gprof is very useful to detect performance bottlenecks but it is not widely utilized. | Not started | Not assigned |
| Add content on dealing with TTYs | Some information of the redesigned TTY subsystem can be found on TTYRedesign. | Not started | Not assigned |

====== Marketing articles ======

The Marketing Team is working on creating a series of whitepapers to explain the advantages of %%FreeBSD%% to a general technical audience.  This material will initially be linked from the new [[https://www.freebsd.org/marketing/|FreeBSD website Marketing page]]. Please mail <<[[/MailTo|MailTo]](marketing AT %%FreeBSD%% DOT org if you are able to write one of these documents.

^ Task ^ Description ^ Status ^ Responsible ^
| %%FreeBSD%% for Solaris users | Write a short article on %%FreeBSD%% for Solaris users. We have support for [[/DTrace]] and [[/ZFS]]. Jails can be a good alternative for zones, so it seems we have a good migration path but we need to document it better. | Not started | Not assigned |
| Clustering with %%FreeBSD%% | Write an article on how to plan a clustered system with %%FreeBSD%%. | Not started | Not assigned |
| %%FreeBSD%% for hosting providers | Write an article on how to use %%FreeBSD%% for common hosting tasks (jails, performance, etc.) | Not started | Not assigned |
| %%FreeBSD%% in embedded devices | Write an article on using %%FreeBSD%% on embedded systems | Not started | Not assigned |
| Building products with %%NetGraph%% | Write an article on how to build a %%FreeBSD%%-based product with Netgraph. | Not started | Not assigned |

====== Misc ======

^ Task ^ Description ^ Status ^ Responsible ^
| Create a source code management book | We use CVS and SVN for mainline development but we also have a Perforce repository and a user area in SVN for experimental development branches. Also, some developers use Mercurial or git for local development. We should collect all information related to the topic to a new book and arrange it in a logical and consistent way. This task would involve SGMLifying the <del>[[/SubversionPrimer|SubversionPrimer]]</del> (done in this [[http://www.freebsd.org/cgi/cvsweb.cgi/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml?f=h;rev=1.310|commit]]), [[/LocalMercurial|LocalMercurial]], and %%LocalGit%% wiki pages and merging our Perforce article to the new book. Some kind of introduction text is also desired to describe how these tools are used. | Not started | Not assigned |
| Write missing manpages | There is a list of missing manpages on [[/MissingManpages|MissingManpages]]. | Not started | Not assigned |
| Add some information on power consumption tuning into the laptop article | [[/TuningPowerConsumption|TuningPowerConsumption]] has some information on the topic, this may be a good starting point. | In progress, [[http://people.freebsd.org/~bcr/laptop_article.html|draft]] | [[/BenedictReuschling|BenedictReuschling]] |
| Add an article on why one should choose %%FreeBSD%% for Java | Elaborate on why one should prefer running Java on %%FreeBSD%% instead of Linux or Solaris. Some information can be found on %%WhyJavaOnFreeBSD%%. | Not started | Not assigned |
| Write section 9 manuals | Document kernel interfaces and functions. | Not started | [[/TomRhodes|TomRhodes]], [[/HitenPandya|HitenPandya]] |
| Documenting %%FreeBSD%% Tunables | Many %%FreeBSD%% tunables are undocumented. Everyone knows how difficult it can be to use an undocumented system, and thus this project was formed. The initial goal here is to create a tool which can generate a manual page with the tunables. Hence we need to generate this list from the source code. | Not started | Not assigned |
| Write a cups article | The CUPS system is more and more used, it would be interesting to have an extensive article in our documentation set. This article should cover CUPS installation and configuration (with examples of local and network printers). | Not started | Not assigned |
| Update architecure-handbook | The %%FreeBSD%% Architecture Handbook is lacking in content, please help us finish this book in writing or updating some chapters. | Not started | Not assigned |
| Contribute advocacy slides/presentations | Presentations marked up in the %%DocBook%%-slides DTD were added a long time ago to doc/en_US.ISO8859-1/slides. More advocacy content is needed, and additional stylesheet work is needed to pull in content from the release notes and other XML content in our documentation set to build up-to-date slides with 'make'. A simple example presentation was committed with some of this functionality, but there is more work to be done! Also, the stylesheets for print/PDF output (using the Java based XSLT processors, %%PassiveTeX%% is too limiting for slides) could be improved as the default %%DocBook%% Slides XSL-FO stylesheets produce very spartan slides. To make this really mature, the infrastructure work described above is also very demanded. | Not started | [[/MurrayStokely|MurrayStokely]] |
| Write a section for Handbook and/or FAQ | Chunks of the FAQ and Handbook have empty sections in them. They need filling. If you have just had to use one of these documents to complete a task, and found them lacking, please find the time to write up your experiences as a possible replacement. Alternatively, if you have just had to do something that had no entry in the FAQ and/or Handbook, please consider writing a new section. | Not started | Not assigned |
| Write new paper on the new SCSI layer for %%FreeBSD%% (CAM) | It would be nice to have a detailed description on this subject. | Not started | Not assigned |
| Release Process | Start collecting some more general notes on the release process, what code freeze means, etc. and update docs. | Not started | [[/BjoernZeeb|BjoernZeeb]] (not really) |
| Commit Messages | Probably update the Committers Guide to include more information on the general format and use cases of and for commit message meta-information as Submitted by: | Not started | [[/BjoernZeeb|BjoernZeeb]] (not really) |
| R-Pi | Given %%FreeBSD%% will soon boot on the r-pi we should ensure to document setup, bringup, use, and possibly later links to cool projects | Not started | Not assigned |

----

{{tag>Docs Stale Todo}}